Merge origin/master into worktree/remove-sdk-project-toolchain
# Conflicts: # .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml # .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md # .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml # .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md # .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md # .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml # .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md # .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml # .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md # .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md # packages/README.i18n.yaml # packages/README.md # packages/scaffold/create-sdk/README.md # packages/scaffold/create-sdk/src/args.ts # packages/scaffold/scripts/src/args.ts # packages/sdk/README.i18n.yaml # scripts/verify-package-readme-model-experience.ts
This commit is contained in:
Tianyi Cui
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
|
||||
2026-06-16-typed-event-schemas.md: c2cff264c7b766d4040d3f7588d436eb7b08140a
|
||||
2026-06-16-typed-event-schemas.md: 8a73970d59fa75cc26e0518e441e704393c692f8
|
||||
2026-06-16-typed-event-schemas.zh.md: 5998be3cea98e1937eb7fe1298cb252cbf3ee171
|
||||
|
||||
@@ -23,7 +23,7 @@ So the real proposal is: **replace the compile-time merge-extensible-map pattern
|
||||
|
||||
## Blast radius (measured)
|
||||
|
||||
A migration of the event/vocabulary surface to runtime schemas touches, at minimum:
|
||||
A migration of the event/vocabulary API to runtime schemas touches, at minimum:
|
||||
|
||||
- **Six merge-extensible maps** (~370 LOC of core types): `ContentBlockMap`, `MessageSourceMap`, `FinishReasonMap` (in `dsh-llm`); `TurnTriggerMap`, `TurnEndReasonMap`, `SessionEventMap` (in `dsh-session`).
|
||||
- **~10 `declare module` augmentation sites** across `dsh-agent`, `dsh-agent-loop`, `dsh-bash`, `dsh-llm`, `dsh-session`, `dsh-session-persistence`, `dsh-system-prompt`, `dsh-tools` — each would move from declaration merging to a runtime `register()` call.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
|
||||
2026-07-06-recallable-compaction.md: 1d62f18c0b63257b45f55ad389a94eae4471f920
|
||||
2026-07-06-recallable-compaction.md: e0817346112d33bfb475430f1a84846aa465d1e0
|
||||
2026-07-06-recallable-compaction.zh.md: e53e669b6111f10701353448927c5e37f4e13e0b
|
||||
|
||||
@@ -107,4 +107,4 @@ Deferred until observation calls for them:
|
||||
- **The stub directory occupies attention**: dozens of stable index cards per request may dilute focus; the bench measurement in the acceptance criteria tracks it against `compact-basic`.
|
||||
- **Cost**: per-pass summarize input is roughly twice today's; short sessions sit near today's cost and quality, and the design pays off with session length.
|
||||
- **State drift and division-of-labor leakage** are observable through the handoff probe and stub review; their counters are specified follow-ups.
|
||||
- **Two backends** are a maintenance surface; the seam contract and the shared recall consumer bound it, and the bench comparison decides the default over time.
|
||||
- **Two backends** are a maintenance burden; the seam contract and the shared recall consumer bound it, and the bench comparison decides the default over time.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
|
||||
2026-07-08-interactive-side-sessions.md: ff7f152b8a106c5b3856846e6980160d1ed59b43
|
||||
2026-07-08-interactive-side-sessions.md: 653f77b931fe1149aad9e15b82f40fe3272f5469
|
||||
2026-07-08-interactive-side-sessions.zh.md: f81a3809231ac18ba6b134abd4a821f47af8b662
|
||||
|
||||
@@ -15,7 +15,7 @@ A **side session** is an ordinary live session forked at the source's last compl
|
||||
- **Fork and attach:** create the child with the parent's balanced completed-turn prefix and stamp `parentSession` and `seedLength` in its metadata. This composes `ctx.agents.create({ seed, meta })`; it adds no core service or session-store method.
|
||||
- **Advisor framing:** inject one plugin-sourced `context/message` after creation that tells the child to explain without mutating or continuing the task. Keeping the system prompt byte-identical preserves the provider prefix cache over inherited history.
|
||||
- **Merge-back:** ask the child for a length-capped handback, then inject one plugin-sourced `context/message` into the parent. The next parent request sees it at its logged position, preserving replay and [request reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) without a new session event.
|
||||
- **Presentation:** invocation, session switching, and handback rendering belong to the first client-owned surface. This Agent Note specifies only the surface-independent mechanics.
|
||||
- **Presentation:** invocation, session switching, and handback rendering belong to the first client UI. This Agent Note specifies only the client-independent mechanics.
|
||||
|
||||
Rewind productization, session-tree views, a model-facing side-session tool, and `forkName`/`mergedInto` metadata are out of scope. A live-adapter spike validated source-log isolation, inherited context, a multi-turn child exchange, and merge-back visibility in the parent's next turn.
|
||||
|
||||
@@ -23,8 +23,8 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
|
||||
|
||||
- **Use the subagent seam:** rejected because side sessions are user-driven, client-visible, and may outlive a parent turn; subagents are model-driven runs returning one tool result.
|
||||
- **Change the child system prompt:** rejected by default because any byte change invalidates the prefix cache from token zero. Deployments may still prefer that stronger separation.
|
||||
- **Add `sidechat/*` events:** deferred because a sourced `context/message` already records the content, producer, and replay input durably. A dedicated event is justified only by a surface that needs distinct rendering.
|
||||
- **Bind a protocol surface now:** rejected because current UIs are client-owned. Live presentation must eventually derive from the durable message so replay renders the same record.
|
||||
- **Add `sidechat/*` events:** deferred because a sourced `context/message` already records the content, producer, and replay input durably. A dedicated event is justified only by a client that needs distinct rendering.
|
||||
- **Bind a protocol API now:** rejected because current UIs are client-owned. Live presentation must eventually derive from the durable message so replay renders the same record.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
@@ -32,10 +32,10 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
|
||||
- Advisor framing adds exactly one plugin-sourced `context/message` at the head of the child's appended history, rather than changing its system prompt.
|
||||
- Merge-back adds exactly one length-capped `context/message` with source `plugin: sidechat`; the next parent request and replay see it at the same position.
|
||||
- Parent and child run concurrently without log or stream cross-talk.
|
||||
- Unit tests cover fork/attach and merge-back; snapshot coverage lands with the first bound surface.
|
||||
- Unit tests cover fork/attach and merge-back; snapshot coverage lands with the first bound UI.
|
||||
|
||||
## Risks
|
||||
|
||||
- Read-only behavior is advisory until a `tools/pre-execute` deny gate enforces it; [the interception point](../../implemented/feature/2026-06-30-interception-extension-points.md) can add that gate without changing these mechanics.
|
||||
- A compacted source forks its compacted view, so a bound surface should disclose that the child inherits summaries rather than replaced turns.
|
||||
- A compacted source forks its compacted view, so a bound UI should disclose that the child inherits summaries rather than replaced turns.
|
||||
- Repeated handbacks consume parent context. The per-merge length cap bounds each note; later consolidation belongs to compaction.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
|
||||
2026-06-11-api-extractor-reports.md: 9c6895f317719294d6eeb4d88a16c3426a2d5b3b
|
||||
2026-06-11-api-extractor-reports.md: 2aee524596a5b798591fecded539a8d2236a3d96
|
||||
2026-06-11-api-extractor-reports.zh.md: e62b6168efac5c8296b55ff8ee0c7861d1849d31
|
||||
|
||||
@@ -8,15 +8,15 @@ English | [中文](2026-06-11-api-extractor-reports.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Public API changes are invisible — nothing makes "this commit changed the public surface" an explicit, reviewable fact. A reviewer reading a diff can miss that an exported type gained a field or a method signature shifted.
|
||||
Public API changes are invisible — nothing makes "this commit changed the public API" an explicit, reviewable fact. A reviewer reading a diff can miss that an exported type gained a field or a method signature shifted.
|
||||
|
||||
## Proposal
|
||||
|
||||
api-extractor (or `tsc --emitDeclarationOnly` + a normalized public-surface dump) producing a checked-in `etc/<pkg>.api.md` per package; CI fails if regeneration differs. Every public-API change becomes a diff line a reviewer (or review agent) must see.
|
||||
api-extractor (or `tsc --emitDeclarationOnly` + a normalized public-API dump) producing a checked-in `etc/<pkg>.api.md` per package; CI fails if regeneration differs. Every public-API change becomes a diff line a reviewer (or review agent) must see.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**`tsc --emitDeclarationOnly` plus a normalized public-surface dump** — the lighter mechanism if api-extractor proves too heavy; either satisfies the checked-in, diffable report shape the proposal needs.
|
||||
**`tsc --emitDeclarationOnly` plus a normalized public-API dump** — the lighter mechanism if api-extractor proves too heavy; either satisfies the checked-in, diffable report shape the proposal needs.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
@@ -25,8 +25,8 @@ api-extractor (or `tsc --emitDeclarationOnly` + a normalized public-surface dump
|
||||
|
||||
## Risks
|
||||
|
||||
The dependency is heavy and finicky — the reason this was deferred — and the report format churns with compiler upgrades, adding a maintenance surface that buys little while the packages stay unpublished.
|
||||
The dependency is heavy and finicky — the reason this was deferred — and the report format churns with compiler upgrades, adding a maintenance burden that buys little while the packages stay unpublished.
|
||||
|
||||
## Why deferred
|
||||
|
||||
Deferred when doc-sync landed: low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency. Revisit if the packages are ever published externally — at that point a stable, diffable public surface earns its keep.
|
||||
Deferred when doc-sync landed: low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency. Revisit if the packages are ever published externally — at that point a stable, diffable public API earns its keep.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
|
||||
2026-07-04-prune-dead-core-spine-surface.md: a2ae3170884bd011676f057004549ff7c93b49d4
|
||||
2026-07-04-prune-dead-core-spine-surface.zh.md: 6bf796f1203683acdb7ea6e2389a7f2996fb8351
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
|
||||
2026-07-04-prune-dead-core-spine-api.md: ac0a72973f9c44e1f322eeff2e095d751497edf8
|
||||
2026-07-04-prune-dead-core-spine-api.zh.md: 9c00025027c11a0ee1a716c3cb3c65d19d71e990
|
||||
@@ -1,8 +1,8 @@
|
||||
# Agent Note: Prune dead public and result surface
|
||||
# Agent Note: Prune dead public API and result fields
|
||||
|
||||
Status: proposed
|
||||
|
||||
English | [中文](2026-07-04-prune-dead-core-spine-surface.zh.md)
|
||||
English | [中文](2026-07-04-prune-dead-core-spine-api.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -10,7 +10,7 @@ Several package-root exports, result fields, and convenience methods have no pro
|
||||
|
||||
The production corpus is `packages/*/*/src`, example sources/config, and runtime scripts. Tests, package READMEs, and Agent Note prose are evidence of publication but not fixed callers. `cordis_inspect` makes `packages/self-modification/tool-cordis/src/api-catalog.ts` model-visible, and `cordis_mount` can invoke injected services through guarded real-service proxies, so catalogued service methods and returned shapes are a genuine dynamic product surface. The table therefore distinguishes absence of a fixed repository caller from unreachability: rows touching catalogued vocabulary intentionally contract what model-written mounts can discover and call, while package-root implementation helpers are not reached through that service façade. Exact-symbol searches produce the following inventory:
|
||||
|
||||
| Surface | Production evidence | Simplification |
|
||||
| API element | Production evidence | Simplification |
|
||||
| --- | --- | --- |
|
||||
| `SurfaceManager.invalidate()` | Only its unit test calls it; seeding completes before the lazily-created manager exists and the session never replaces its log reference. | Delete it and its impossible wholesale-replacement contract. |
|
||||
| `ToolExecutionResult.callId` | Every hook already receives the immutable `ToolExecution`; the loop and ACP correlate through the call/session event. No consumer reads the duplicate result field. | Remove the field, copy/mismatch guards, and tests that prove the duplicate cannot disagree. |
|
||||
@@ -49,12 +49,12 @@ Remove or demote every row as one bounded coordinated public-surface cleanup. Up
|
||||
|
||||
**Keep test conveniences and self-contained results public.** Public helpers can make white-box tests convenient, self-contained result fields can look ergonomic, and future embedders might want the concrete loop or enumeration methods. Those benefits are hypothetical; today they make every implementation and document explain states that no shipped caller can observe. A real consumer can introduce the smallest contract it needs, with its ownership and failure semantics known.
|
||||
|
||||
**Keep every catalogued member for model-written mounts.** The self-referential toolset is a real generic consumer route, not generated-doc noise. Its value comes from an accurate, composable service surface, however, not from preserving duplicate fields or incoherent argument pairs indefinitely; each catalogued contraction above removes a fact available elsewhere on the same execution, agent, or result and updates the API reference in the same change.
|
||||
**Keep every catalogued member for model-written mounts.** The self-referential toolset is a real generic consumer route, not generated-doc noise. Its value comes from an accurate, composable service API, however, not from preserving duplicate fields or incoherent argument pairs indefinitely; each catalogued contraction above removes a fact available elsewhere on the same execution, agent, or result and updates the API reference in the same change.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- Exact-symbol searches show no removed surface outside this Agent Note and any implemented-Agent Note amendments.
|
||||
- Every surface listed in this Agent Note is absent or demoted as specified; deliberately retained extension/test contracts outside the inventory are unchanged.
|
||||
- Exact-symbol searches show no removed API outside this Agent Note and any implemented-Agent Note amendments.
|
||||
- Every API element listed in this Agent Note is absent or demoted as specified; deliberately retained extension/test contracts outside the inventory are unchanged.
|
||||
- Tool execution, compaction, both LLM adapters, both persistence backends, workflow isolation, and agent creation/resume retain their shipped behavior.
|
||||
- Typecheck, coverage, snapshots, doc-sync, module-graph verification, build, and hygiene pass.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Status: proposed
|
||||
|
||||
[English](2026-07-04-prune-dead-core-spine-surface.md) | 中文
|
||||
[English](2026-07-04-prune-dead-core-spine-api.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
Reference in New Issue
Block a user