Skip to content

feat(mar-887): shared agent SDK file inside the agent folder - #356

Merged
Thebeatkicks merged 7 commits into
masterfrom
000henrik/mar-887-agent-sdk
Sep 7, 2026
Merged

Thebeatkicks merged 7 commits into
masterfrom
000henrik/mar-887-agent-sdk

Conversation

@Thebeatkicks

Copy link
Copy Markdown
Contributor

Stage 1 of MAR-886. There were two copies of the agent runtime and no shared
module; ADR 0032 recorded the fork as a later packet's job, and this is that
packet.

What this is

agent-kit/template/dash-agent-sdk.mjs is the runtime as one self-contained ESM
file — node builtins only, no package, no node_modules — that ships inside
the agent folder
beside agent.mjs and is imported from it by relative path.
Both scaffolders and the packaged sample write the same bytes.

The templates keep their definition and their task logic and nothing else:
agent-kit/template/agent.mjs goes from 1060 lines to 554,
tools/dash-mcp/template/agent.mjs from 743 to 416. brief-fingerprint.mjs is
absorbed into the runtime, which already carried the same do not edit warning;
DASH's half stays at lib/brief/fingerprint.ts and the mirror test still pins
the two halves against each other.

Why a file rather than a dependency

agent-kit/scaffold.ts writes dependencies: {} on purpose, and the packaged
sample is copied as raw bytes into the user's Documents folder by
scripts/build-shell.mjs. There is no install step anywhere in the installed
journey and no place to put one a person would forgive. Bundling the runtime
into agent.mjs at scaffold time was the other candidate and destroys the
property the split exists for: a runtime fix that reaches an agent somebody has
been editing for months without touching their file. ADR 0034 has both
arguments.

Nothing the runner sees changed

Same seven telemetry types at event_version: 1, the same seq/ts
discipline, the same artifact shapes at versions 1 and 2, the same four
acknowledged commands, the same waiting task. The one place a shape could have
moved — the digest's generated_at, which one template stamped and the other
did not — is resolved by stamping it only when the author did not, so both
templates emit the same keys in the same order they did before.

Old agents are untouched and keep working: ADR 0008 makes the folder the unit
and nothing rewrites agent.mjs in place, so every agent generated before this
is still monolithic and spawned by a runner that did not change.
tests/legacy-agent.test.ts spawns those exact bytes (cb2cb1c, kept at
tests/fixtures/legacy-agent-kit-template.mjs) under a real Supervisor.

Verified

  • pnpm typecheck clean.
  • pnpm test — 283 files, 5352 passed, 13 skipped, 0 failed.
  • pnpm build:agent-kit, then the real CLI: a scaffold on disk carrying
    agent.mjs and dash-agent-sdk.mjs.
  • pnpm build:renderer; pnpm build:shell — dist/electron/agent-kit/ holds
    both files.
  • The installed-style shell smoke on a scratch store: 85 PASS / 0 FAIL,
    [smoke] all proofs passed. 6b lists dash-agent-sdk.mjs in the handoff
    DASH creates, 6c-f shows code/dash-agent-sdk.mjs accepted with its hash
    into DASH's own stored copy, and 6d–6k are the acceptance sentence run
    against a real generated agent through the SDK: it waits to be asked, nothing
    runs on its own, Run now goes through the audited bridge, telemetry renders
    compliant: true with no sequence gap, and the digest reaches both the folder
    and DASH. Runner retired with scripts/retire-scratch-runners.mjs (202).

Evidence class: fixture tests plus an installed-style shell on a scratch store.
The real store was never opened; the installed-build proof is the orchestrator's.

docs/foundation/stage-1-handoff.md carries the deviations, what is not done,
and what the next session should read first.

🤖 Generated with Claude Code

Thebeatkicks and others added 7 commits September 7, 2026 17:04
Both agent templates carried a full copy of the runtime: the runner
protocol, telemetry v1, the artifact shapes, the broker and browser
channels, the command acknowledgements and the idle-until-asked state
machine. ADR 0032 recorded the fork as a later packet's job; this is
that packet.

`agent-kit/template/dash-agent-sdk.mjs` is that runtime as one
self-contained ESM file, node builtins only, shipped inside the agent
folder and imported by `agent.mjs` with a relative path. It absorbs
`brief-fingerprint.mjs`, so the mirror DASH pins is now one file rather
than two.

The templates keep their definition and their task logic and nothing
else. Every message the runner sees is unchanged: same telemetry, same
artifact key order, same acknowledgements, same waiting task.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…mport

`TemplateSources` gained `sdk`, so every fixture that stood in for the
template files carries it. `scout-curates` copies both files rather than
the program alone, because a relative import that resolves to nothing is
a process that dies before it can be watched. The fingerprint mirror now
compares DASH's half against the runtime, which is where that function
went.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…dates it

Two things no spawning test can see. `tests/agent-sdk.test.ts` holds the
runtime to the property that makes it shippable at all: node builtins
only, no bare specifier and no dynamic import, because a scaffold
declares no dependencies and the packaged sample is copied as bytes.
`tests/legacy-agent.test.ts` spawns the monolithic template as it stood
at cb2cb1c under a real Supervisor, because the agents at risk from this
change are not on this branch, they are on people's disks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
ADR 0034 records the decision and the two shapes it rejects: an npm
package, which fails at the only place that matters (a scaffold declares
no dependencies and the packaged sample is copied as bytes), and
bundling the runtime into agent.mjs at scaffold time, which destroys the
one property the split exists for.

`docs/foundation/sdk-upgrades.md` states the rule the version is for --
an upgrade replaces `dash-agent-sdk.mjs` and never touches `agent.mjs` --
and says plainly that the mechanism is not built, and why: there is no
hook in `lib/sample-refresh.ts` to ride, and a write into a stored agent
folder is a write ADR 0008 says the next import discards.

Both READMEs and the skill now name the file an author edits and the one
they must not, in that order.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…e lives

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Thebeatkicks
Thebeatkicks marked this pull request as ready for review September 7, 2026 15:36
@Thebeatkicks
Thebeatkicks merged commit 1d7c4e7 into master Sep 7, 2026
2 checks passed
Thebeatkicks added a commit that referenced this pull request Sep 7, 2026
…ce log

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant