kevchess15/deepseek-harness
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
deepseek-harness/packages/README.md

72 lines
7.9 KiB
Markdown
Raw Normal View History

Document the codebase thoroughly and tighten type safety Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
# Packages
docs: translate remaining READMEs
2026-07-26 05:03:53 +08:00
English | [中文](README.zh.md)
docs(packages): keep package index within budget
2026-08-09 23:38:37 +08:00
npm scope: `@deepseek-ai/dsh-*`; Cordis `Service` subclasses and function plugins contribute through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Rules: [package](AGENTS.md), [root](../AGENTS.md#conventions).
Document the codebase thoroughly and tighten type safety Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
Document the package hierarchy and finalize the RFC Add a README to each group dir (core/llm/bash/session-persistence/ui/ support) stating its role and product-vs-support classification, and rewrite packages/README.md around the hierarchy (group table, grouped "what goes where", removed the package-hierarchy FIXME). Move the package-hierarchy RFC to implemented/architecture/ and rewrite it to describe what shipped (placement rationale, the paths-wildcard and publint dedup, the two new guardrail gates). Fold the remaining tsconfig.build.json references dedup into the discover-package-inventory proposal and fix its cross-link. Update AGENTS.md: regrouped repo-layout map, depth-2 globs, the new verify-package-paths gate in the doc-sync listing, and a note that we lean toward stricter lint in the agentic-coding era (machine-caught errors and a consistent foundation outweigh the one-time cost).
2026-06-20 23:25:33 +08:00
## Hierarchy
fix(rebase): migrate the replayed E2B branch onto the rebased parent The linear replay carried old-lineage content over parent-owned files; this checkpoint restores them and adapts the branch to the parent's post-rebase seam: - restore all pty/lsp/subprocess/code-runtime surfaces to the parent's exact content (this branch claims none of them) and drop the net-zero code-runtime-e2b/pty-e2b/lsp-e2b residue and its registrations - widen serializeRemoteEnvironment to the seam's NodeJS.ProcessEnv tombstone contract: an explicit undefined removes an ambient entry - migrate the two E2B fixture Agent stubs to the Inbox-model interface and Session.create - re-apply the branch's gen-doc-graphs roles, THIRD_PARTY_NOTICES e2b row, and packages/README group row (trimmed to the doc budget); regenerate catalogs and re-record bilingual pairings
2026-08-07 21:04:33 +08:00
Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
Document the package hierarchy and finalize the RFC Add a README to each group dir (core/llm/bash/session-persistence/ui/ support) stating its role and product-vs-support classification, and rewrite packages/README.md around the hierarchy (group table, grouped "what goes where", removed the package-hierarchy FIXME). Move the package-hierarchy RFC to implemented/architecture/ and rewrite it to describe what shipped (placement rationale, the paths-wildcard and publint dedup, the two new guardrail gates). Fold the remaining tsconfig.build.json references dedup into the discover-package-inventory proposal and fix its cross-link. Update AGENTS.md: regrouped repo-layout map, depth-2 globs, the new verify-package-paths gate in the doc-sync listing, and a note that we lean toward stricter lint in the agentic-coding era (machine-caught errors and a consistent foundation outweigh the one-time cost).
2026-06-20 23:25:33 +08:00
| Group | Role | Release expectation |
|---|---|---|
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable API |
refactor: apply repository naming contract Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
2026-08-13 00:36:22 +08:00
| [`api/`](api/README.md) | Remote BFF assembly and Typert RPC gateway | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable API |
| [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable API |
Merge remote-tracking branch 'origin/master' into worktree/schedule-conversational-after
2026-08-11 19:05:13 +08:00
| [`schedule/`](schedule/README.md) | Session-local scheduled follow-ups | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`feedback/`](feedback/README.md) | Human feedback | Product — stable API |
refactor: apply repository naming contract Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
2026-08-13 00:36:22 +08:00
| [`identity/`](identity/README.md) | Shared anonymous identity | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable API |
docs(packages): fit merged group map budget
2026-07-28 18:38:45 +08:00
| [`e2b/`](e2b/README.md) | E2B providers | POC |
fix(sandbox): contain drain failure settlement
2026-08-19 06:35:50 +08:00
| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition, local process-tree provider, and shared Win32 process library | Product — stable API |
refactor: apply repository naming contract Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
2026-08-13 00:36:22 +08:00
| [`shell/`](shell/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable API |
| [`terminal/`](terminal/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable API |
| [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable API |
| [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable API |
| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable API |
| [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable API |
refactor: apply repository naming contract Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
2026-08-13 00:36:22 +08:00
| [`compaction/`](compaction/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable API |
| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry contract and the model-facing delegation tool | Product — stable API |
refactor: apply repository naming contract Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
2026-08-13 00:36:22 +08:00
| [`jobs/`](jobs/README.md) | Generic background-job runtime and model-facing `job_*` control tools | Product — stable API |
refactor(team): incubate Agent Teams packages
2026-08-18 11:11:34 +08:00
| [`experimental/`](experimental/README.md) | Private prototypes and internal-only plugins | Unreleased |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable API |
feat(webhook): create workspace sessions from GitHub events
2026-08-22 23:44:56 +08:00
| [`webhook/`](webhook/README.md) | Verified external events, rules, and fire-and-forget Workspace Sessions | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable API |
| [`attachment/`](attachment/README.md) | Durable attachment identity, validation, local content-addressed storage | Product — stable API |
| [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable API |
| [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable API |
| [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable API |
| [`preset/`](preset/README.md) | Per-session agent composition from preset `cordis.yml` files | Product — stable API |
| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer | Product — stable API |
| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable API |
fix: rebase 3
2026-08-13 02:29:17 +08:00
| [`extensions/`](extensions/README.md) | Agent runtime self-modification: live plugin/service inspection and model-written plugin mount/unmount ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable API |
| [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable API |
| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable API |
| [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable API |
feat(authorization): obtain a credential by asking the human Some credentials cannot be configured, only obtained: getting one means a conversation — open this page, paste that code, pick an account. The new seam owns that conversation and the one-attempt-per-key lifecycle, and never the protocol, so a second authorization protocol arrives as another flow rather than as another seam. A flow is registered under the CredentialKey it writes, which is also how the seam knows which plugin answers for the format inside that record. The flow owns the write: run() resolving means the record is already committed through ctx.credentials, and the seam confirms it. That keeps a library persisting through its own store adapter the single writer instead of being copied back out and written twice. The interaction travels with the request rather than a registry, because whoever starts an authorization is the one who can talk to the human about it. A request already withdrawn never claims the key and never starts the flow — relying on each flow to check its signal before the first await would let one that does not hang holding the key.
2026-08-13 15:33:29 +08:00
| [`credentials/`](credentials/README.md) | Credential reference/record seam + env-over-`.env` provider + authorization flows | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable API |
| [`workspace/`](workspace/README.md) | Workspace entity | Product — stable API |
docs(python): make the dsh profile runtime current Document dsh as the only application launcher across architecture, CLI, SDK, app-boot, Python package, contributor, tutorial, and example references. Explain explicit home selection, profile and patch precedence, persistent external plugin installation, the Node-free runtime path, and the absence of complete-config or ~/.dsh fallbacks. Record the Python profile-runtime decision and update the active naming, installed-wheel, and SEA packaging notes with precise supersession. Regenerate the configuration catalog and module graph after deleting the carrier, update both reviewed languages and pairing records, and classify the retained standalone Cordis files as lower-level test fixtures rather than launch interfaces.
2026-08-23 14:56:55 +08:00
| [`sdk/`](sdk/README.md) | Out-of-process SDK: JSON-RPC protocol and TypeScript client/server | Product — stable API |
refactor: replace overloaded surface terminology
2026-07-24 19:54:25 +08:00
| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable API |
| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable API |
| [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable API |
| [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable API |
| [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable API |
refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later.
2026-08-23 01:48:26 +08:00
| [`examples/`](examples/README.md) | Reusable demo bundles for runnable example leaves | Support — example infra |
refactor: apply repository naming contract Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
2026-08-13 00:36:22 +08:00
| [`test-support/`](test-support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
Merge remote-tracking branch 'origin/master' into codex/agent-session-jsonl-location # Conflicts: # docs/config-catalog.md # docs/module-graph.md # docs/rfc/INDEX.md # packages/README.md # packages/bash/bash-local/README.md # packages/bash/bash/README.md # packages/bash/tool-bash/README.md # packages/bash/tool-bash/tests/tools.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/examples/acp-demo/src/index.ts # packages/examples/acp-demo/tests/acp-agent.spec.ts # packages/examples/agent-spine-demo/README.md # packages/examples/agent-spine-demo/src/index.ts # packages/examples/agent-spine-demo/tests/agent-core.spec.ts # packages/examples/stdio-demo/src/index.ts # packages/examples/stdio-demo/tests/stdio-agent.spec.ts # packages/util/README.md # pnpm-lock.yaml # tsconfig.build.json # tsconfig.json
2026-07-17 18:35:48 +08:00
| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
Document the package hierarchy and finalize the RFC Add a README to each group dir (core/llm/bash/session-persistence/ui/ support) stating its role and product-vs-support classification, and rewrite packages/README.md around the hierarchy (group table, grouped "what goes where", removed the package-hierarchy FIXME). Move the package-hierarchy RFC to implemented/architecture/ and rewrite it to describe what shipped (placement rationale, the paths-wildcard and publint dedup, the two new guardrail gates). Fold the remaining tsconfig.build.json references dedup into the discover-package-inventory proposal and fix its cross-link. Update AGENTS.md: regrouped repo-layout map, depth-2 globs, the new verify-package-paths gate in the doc-sync listing, and a note that we lean toward stricter lint in the agentic-coding era (machine-caught errors and a consistent foundation outweigh the one-time cost).
2026-06-20 23:25:33 +08:00
refactor(schedule): keep reminder delivery conversational
2026-08-09 15:22:53 +08:00
New packages join existing groups; new groups update their README and this table.
refactor(examples): extract reusable logic into tested packages Logic that lived under examples/ was outside the per-file 100% coverage gate (examples/ are not workspaces) and, in the stdio-UI case, duplicated across two examples. Move it into packages/ so it is gated and de-duped. - packages/ui-stdio (new): unify the two diverged stdio-chat.ts copies into one @deepseek-ai/dsh-ui-stdio plugin (welcome/agent Config). A test-only I/O seam (createStdioChat(ctx, config, runtime)) keeps process streams out of the serializable config and makes every render/EOF/disposal branch unit-testable. Per-file 100%. echo/coding cordis.yml now load the package; both src/stdio-chat.ts deleted. - packages/llm-replay (new): move examples/acp-agent/src/llm-replay.ts (+ its spec) here so its derive/parse/replay branches fall under the coverage gate. cordis.snapshot.yml + README rewired to the package name; added apply/env /assertNever/abort tests to reach per-file 100%. - examples/{echo,coding}-agent: keyless Loader-path e2e smokes that boot the real cordis.yml (no key) — the guard a hand-mounted unit test cannot be for the unwrapExports/export-shape class (postmortem 0001). examples/AGENTS.md codifies the keyless+with-key smoke convention (keyless-by-nature exception for echo-agent). - AGENTS.md: a scoped, removal-triggered pre-release stance (foundation over blast radius). packages/README.md: new rows + a FIXME to later regroup ALL packages into a hierarchy. Wiring: tsconfig paths/refs, publint, knip, module-graph. Verified: typecheck, lint, test:coverage (887 tests, 100%), build, hygiene, doc-sync, test:snapshot (10), test:e2e (6 keyless pass, with-key self-skip).
2026-06-19 12:42:28 +08:00
docs(AGENTS): rewrite the root standing orders to the 1,500-word budget Applies the documentation standard to its biggest offender. Every rule survives as one to three lines plus a link to its durable home; the stories, duplicate statements, and re-narrations go: - Situational clusters evict to new homes: docs/testing.md (tiers, with-key policy, real-over-mock, world-verification, real-entry-path guards), docs/defensive-patterns.md (the bug-class rules), and docs/cookbook/responding-to-pr-review-on-a-stack.md (the stacked-PR review procedure). - Doc-authoring rules consolidate into docs/AGENTS.md § Writing rules (current-state-never-history, md-wrap, ts-block compilation, @mode, catalog same-change, pair same-change). - packages/README.md drops to the group table + the extension-vs-bundle dependency rule; the hand ASCII graph yields to the generated module-graph.md; group READMEs are the canonical per-package map. - packages/AGENTS.md keeps only its packages-specific rules (export shape, ctx.get, real-Loader coverage); examples/AGENTS.md repoints its with-key-policy link; rfc/README.md loses a narrated-history aside; dsh-code-review / dsh-find-simplifications / verify-md-wrap references follow the moved content. - Budget manifest ratchets: AGENTS.md 8200 -> 1500 (now 1,495 words), packages/README.md 1900 -> 600, packages/AGENTS.md 600 -> 450; the two new eviction docs join the budget set (testing 800, defensive 550); docs/AGENTS.md raises 1000 -> 1250 for the absorbed writing rules (the one justified increase). The doc-tiers RFC's deferred list prunes the two items this change ships.
2026-07-04 14:22:47 +08:00
## Dependencies
Document the codebase thoroughly and tighten type safety Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
fix: address master merge gate failures
2026-07-09 13:01:14 +08:00
The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
Document the codebase thoroughly and tighten type safety Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
docs: capitalize Service Provider across repository
2026-08-13 11:55:38 +08:00
**Extension plugins depend on Service Definitions, never concrete providers.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities separate Service Definition / Service Provider / Consumer roles when they evolve independently; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
Document the codebase thoroughly and tighten type safety Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
2026-06-11 12:39:27 +08:00
docs: harden package README gates
2026-07-14 14:01:35 +08:00
Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
Reference in a new issue Copy permalink