Skip to content

Add the Actor contract design doc - #111

Merged
danielgwilson merged 1 commit into
mainfrom
actor-contract-adr
Jun 6, 2026
Merged

Add the Actor contract design doc#111
danielgwilson merged 1 commit into
mainfrom
actor-contract-adr

Conversation

@danielgwilson

@danielgwilson danielgwilson commented Jun 6, 2026

Copy link
Copy Markdown
Owner

Summary

The design doc for the Actor contract — the foundation of the multi-harness leap. It is the durable API surface the adapters will depend on, so it lands before implementation, reviewable up front.

Today Mimetic has one actor (Codex) behind a hardcoded dispatch. This contract makes the actor layer pluggable so the same persona scenario can run across the harnesses our users actually run (Codex, the pi stack, Claude Agent SDK, and a computer-use lane), all emitting one public-safe evidence schema.

What it specifies

  • Actor interface + mimetic.actor-trace.v1 normalized evidence schema (Codex item/*, Claude ToolUse/ToolResult, pi tool_execution_*, and computer_call cycles all map onto one items[]).
  • Injected RedactionHooks (one redaction implementation, completing Redact absolute workspace path in blocked-TUI bundle + close verify scanner /tmp blind spot #107) and an ApprovalPolicy for unattended runs.
  • Capability-aware dispatch: the registry refuses a code-only actor for a GUI scenario (coverage honesty over green-by-construction).
  • The plan to make persona traits load-bearing: patience becomes a harness-enforced turn budget ending in gave_up, verified by a persona-fidelity check.

Key decisions

  • Transport-agnostic contract; Codex stays the reference, pi-agent-core is the first in-process-SDK adapter.
  • A run is multi-turn within one trace.
  • Stagehand fronts the volatile computer-use providers; screenshots are field-blurred + OCR-scrubbed before any public artifact.

Sequencing (this doc is step 1)

  1. This doc.
  2. Shared RedactionHooks + Actor types; Codex refactored to implement Actor; registry; RunStream.codex → RunStream.actor.
  3. Personas load-bearing.
  4. pi-agent-core adapter → 5. Claude Agent SDK → 6. Stagehand computer-use → 7. cross-harness conformance test → 8. the OSS proof point.

Proof

release:check        green (typecheck/test/build/public-surface/skill/pack)
pack                 ships docs/architecture/actor-contract.md (13.4kB)

Docs only; no code change.

🤖 Generated with Claude Code

@danielgwilson @claude
Add the Actor contract design doc
ab1f9c9 
Defines the provider-neutral Actor contract that makes Mimetic's actor layer
harness-pluggable: one `mimetic.actor-trace.v1` evidence schema, an injected
RedactionHooks, an ApprovalPolicy for unattended runs, capability-aware dispatch,
and the plan to make persona traits load-bearing (patience as a harness-enforced
turn budget). Codex stays the reference adapter; pi-agent-core, the Claude Agent
SDK, and a Stagehand computer-use lane are the first new adapters.

This is the durable API surface the adapters depend on, captured before
implementation so the contract is reviewable up front. Staged sequencing and
risks are included; links the remaining redaction-module work (#107) and the
PII/PHI detector (#108).

Docs only. release:check green; the doc ships via files[] docs/architecture.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@danielgwilson
danielgwilson merged commit 105386f into main Jun 6, 2026
3 checks passed
@danielgwilson
danielgwilson deleted the actor-contract-adr branch June 6, 2026 22:00
@danielgwilson danielgwilson mentioned this pull request Jun 7, 2026
Merged
danielgwilson added a commit that referenced this pull request Oct 2, 2026
@danielgwilson @claude
Count prose in src string literals in prose:check
e94e17e 
scripts/check-code-prose.mjs counts comments and test names, so the
text a person reads in errors, warnings and command output kept every
class the comment passes removed. It now also walks oxc's string
Literal and TemplateElement nodes under src/ and counts six kinds, each
held to its own --max-string-* flag at today's count:

- string-em-dashes: 172
- string-issue-refs: 11 (one to five digits, as comments count them; a
  CSS color like `color:#111` or `solid #111}` and an HTML entity like
  `&#39;` are not references)
- string-slice: 10 ("a later slice" and its kin)
- string-rationale: 34 ("fail closed", "by construction", "hollow",
  "honest", "safety lie")
- string-plural-s: 62 ("turn(s)"; "http(s)" is a URL scheme and does
  not count)
- string-caps: 339 (the same CAPS_RUN and ACRONYMS as comments; names
  inside embedded shell and python scripts count too, so this cap is a
  ratchet, not a target of 0)

Code spans inside a string are not counted. Model prompts
(participant-prompt.ts, lobby-code.ts) and the terminal's ASCII
transcoding table (encoding.ts) are excluded. Strings under tests/,
scripts/ and tui/ are not counted. No source string changes here; the
cleanup passes lower the caps.

tests/scripts/check-code-prose.test.ts covers each string kind; the
CSS, entity, http(s) and code-span exclusions; comments and strings
counted apart; strings counted only under src; and failure above and
below --max-string-em-dashes. AGENTS.md and CONTRIBUTING.md state the
rule for messages.

Checked: the test file (20 tests), prose:check, tsc, format, and the
full gate (results in the PR). Not checked: which of the 339 caps hits
are emphasis and which are names; the passes sort that out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
danielgwilson added a commit that referenced this pull request Oct 2, 2026
@danielgwilson @claude
Count prose in src string literals in prose:check
625eb11 
scripts/check-code-prose.mjs counts comments and test names, so the
text a person reads in errors, warnings and command output kept every
class the comment passes removed. It now also walks oxc's string
Literal and TemplateElement nodes under src/ and counts six kinds, held
in scripts/caps.json at prose.src.string-* at today's counts:

- string-em-dashes: 160
- string-issue-refs: 10 (one to five digits, as comments count them; a
  CSS color like `color:#111` or `solid #111}` and an HTML entity like
  `&#39;` are not references)
- string-slice: 10 ("a later slice" and its kin)
- string-rationale: 30 ("fail closed", "by construction", "hollow",
  "honest", "safety lie")
- string-plural-s: 62 ("turn(s)"; "http(s)" is a URL scheme and does
  not count)
- string-caps: 278 (isCapsEmphasis from lib/prose-rules.mjs; names in
  embedded shell and python scripts count too, so this cap is a
  ratchet, not a target of 0)

Not counted: code spans inside a string; string literal types
(`"fail-closed" | "record-evidence"`); model prompts in
src/analysis/execute.ts, participant-prompt.ts and lobby-code.ts; the
terminal's ASCII transcoding table in encoding.ts; and the statement
right after a `prose-check: model prompt` comment, for prompts that
live beside messages. Strings under tests/, scripts/ and tui/ are not
counted. No source string changes here; the cleanup passes lower the
caps.

tests/scripts/check-code-prose.test.ts covers each string kind; the
CSS, entity, http(s) and code-span exclusions; the prompt marker; type
literals; strings counted only under src; and failure above and below
the string-em-dashes cap. AGENTS.md and CONTRIBUTING.md state the rule
for messages.

Checked: tests/scripts (193 tests), prose:check, tsc, format, and the
full gate (results in the PR). Not checked: which of the 278 caps hits
are emphasis and which are names; the passes sort that out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
danielgwilson added a commit that referenced this pull request Oct 2, 2026
@danielgwilson @claude
Count prose in src string literals in prose:check
e0c464e 
scripts/check-code-prose.mjs counts comments and test names, so the
text a person reads in errors, warnings and command output kept every
class the comment passes removed. It now also walks oxc's string
Literal and TemplateElement nodes under src/ and counts six kinds, held
in scripts/caps.json at prose.src.string-* at today's counts:

- string-em-dashes: 160
- string-issue-refs: 10 (one to five digits, as comments count them; a
  CSS color like `color:#111` or `solid #111}` and an HTML entity like
  `&#39;` are not references)
- string-slice: 10 ("a later slice" and its kin)
- string-rationale: 30 ("fail closed", "by construction", "hollow",
  "honest", "safety lie")
- string-plural-s: 62 ("turn(s)"; "http(s)" is a URL scheme and does
  not count)
- string-caps: 278 (isCapsEmphasis from lib/prose-rules.mjs; names in
  embedded shell and python scripts count too, so this cap is a
  ratchet, not a target of 0)

Not counted: code spans inside a string; string literal types
(`"fail-closed" | "record-evidence"`); model prompts in
src/analysis/execute.ts, participant-prompt.ts and lobby-code.ts; the
terminal's ASCII transcoding table in encoding.ts; and the statement
right after a `prose-check: model prompt` comment, for prompts that
live beside messages. Strings under tests/, scripts/ and tui/ are not
counted. No source string changes here; the cleanup passes lower the
caps.

tests/scripts/check-code-prose.test.ts covers each string kind; the
CSS, entity, http(s) and code-span exclusions; the prompt marker; type
literals; strings counted only under src; and failure above and below
the string-em-dashes cap. AGENTS.md and CONTRIBUTING.md state the rule
for messages.

Checked: tests/scripts (193 tests), prose:check, tsc, format, and the
full gate (results in the PR). Not checked: which of the 278 caps hits
are emphasis and which are names; the passes sort that out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
danielgwilson added a commit that referenced this pull request Oct 2, 2026
@danielgwilson @claude
Count prose in src string literals in prose:check (#1445)
b7be454 
scripts/check-code-prose.mjs counts comments and test names, so the
text a person reads in errors, warnings and command output kept every
class the comment passes removed. It now also walks oxc's string
Literal and TemplateElement nodes under src/ and counts six kinds, held
in scripts/caps.json at prose.src.string-* at today's counts:

- string-em-dashes: 160
- string-issue-refs: 10 (one to five digits, as comments count them; a
  CSS color like `color:#111` or `solid #111}` and an HTML entity like
  `&#39;` are not references)
- string-slice: 10 ("a later slice" and its kin)
- string-rationale: 30 ("fail closed", "by construction", "hollow",
  "honest", "safety lie")
- string-plural-s: 62 ("turn(s)"; "http(s)" is a URL scheme and does
  not count)
- string-caps: 278 (isCapsEmphasis from lib/prose-rules.mjs; names in
  embedded shell and python scripts count too, so this cap is a
  ratchet, not a target of 0)

Not counted: code spans inside a string; string literal types
(`"fail-closed" | "record-evidence"`); model prompts in
src/analysis/execute.ts, participant-prompt.ts and lobby-code.ts; the
terminal's ASCII transcoding table in encoding.ts; and the statement
right after a `prose-check: model prompt` comment, for prompts that
live beside messages. Strings under tests/, scripts/ and tui/ are not
counted. No source string changes here; the cleanup passes lower the
caps.

tests/scripts/check-code-prose.test.ts covers each string kind; the
CSS, entity, http(s) and code-span exclusions; the prompt marker; type
literals; strings counted only under src; and failure above and below
the string-em-dashes cap. AGENTS.md and CONTRIBUTING.md state the rule
for messages.

Checked: tests/scripts (193 tests), prose:check, tsc, format, and the
full gate (results in the PR). Not checked: which of the 278 caps hits
are emphasis and which are names; the passes sort that out.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@danielgwilson