The job agent takes Relay's header and returns Relay's state block

spec:cc-agents.relay-job-type

Use Case / Behavior · featureready floor ready

Packs: none

Design: 6 design entries · 6 pinned declarations · no decisions

specs/runner/relay-job-type.sdp.md

4 open questions and no blocking questions; implementation binding present, verifier binding present, and expected-outcome oracle none.

The agent type cc-agents:job lets Workflow scripts and protocols written for Relay's relay:job run on this plugin's harnesses by changing only their agent type. The header is translated in plugin/sidecar/relay-header.mjs; the mod returns the state block and recovers a resumed Workflow role.

Intent

actor: An author of Workflow scripts and protocols written for Relay's job agent.
problem: Those scripts read Relay's header, state block and report path, and are many; rewriting each for a new agent type would stop the migration.
outcome: The same scripts run unchanged but for the agent type, and a Workflow resumed after a crash continues or returns its roles.
value: Existing multi-day Workflow protocols move to this plugin without being rewritten.

Open questions

non-blocking · question.endedBlocks line 27 · specs/runner/relay-job-type.sdp.md:27 · The block of a job that was cancelled or failed, with state cancelled or failed and an error line, and a relative add-dir refused, are built and no test pins them.Decider: delegatedProvisional: As built.
non-blocking · question.writeNotYolo line 30 · specs/runner/relay-job-type.sdp.md:30 · Relay's job defaulted to a sandbox-free mode, while this agent defaults to write and runs without a sandbox only when the header states yolo.Decider: ownerProvisional: Write by default, with a note in the state block, as built.
non-blocking · question.ignoredKeys line 33 · specs/runner/relay-job-type.sdp.md:33 · The keys fast, grok-home and kimi-home are accepted and ignored with a note, and the notes' wording is not pinned by a test.Decider: delegatedProvisional: Accepted and ignored, as built.
non-blocking · question.opencodeBackendsAndYolo line 36 · specs/runner/relay-job-type.sdp.md:36 · Backends kimi, grok and zcode run on OpenCode, which refuses yolo, so a job that states yolo on those backends is refused by the check; no test pins that.Decider: ownerProvisional: Described as built.

Behavior

rule.sameHeader line 42 · specs/runner/relay-job-type.sdp.md:42: The header takes Relay's keys backend, model, effort, mode, network, web-search, cd, add-dir, brief, fast, grok-home and kimi-home, and refuses any other key, a relative cd, and add-dir in read-only mode.
no example exercises it
rule.backends line 43 · specs/runner/relay-job-type.sdp.md:43: Backend codex runs on Codex, and kimi, grok and zcode run on OpenCode under the providers that serve them, with Relay's Kimi alias mapped, and a model named for another backend with no backend stated is refused.
no example exercises it
rule.writeByDefault line 44 · specs/runner/relay-job-type.sdp.md:44: The mode is write unless stated, with a note saying that Relay's default was yolo, and yolo only when the header states it.
no example exercises it
rule.optionsReachCodex line 45 · specs/runner/relay-job-type.sdp.md:45: The add-dir, network and web-search keys reach Codex's sandbox, with add-dir on top of the user's extra writable folders.
no example exercises it
rule.briefFile line 46 · specs/runner/relay-job-type.sdp.md:46: A brief names an absolute file whose text is the task, nothing may follow the header's dashes then, and a job with no brief is refused.
no example exercises it
rule.stateBlock line 47 · specs/runner/relay-job-type.sdp.md:47: A job returns Relay's state block of lines state, job, backend, model, effort, mode, duration, report and dir, then automatic-resume and note lines where they apply, and Relay's parser reads it as before.
no example exercises it
rule.blockAloneInWorkflow line 48 · specs/runner/relay-job-type.sdp.md:48: In a Workflow the block alone is the result, and outside a Workflow it is followed by a line --- and the report.
no example exercises it
rule.reportIsAFile line 49 · specs/runner/relay-job-type.sdp.md:49: The report is written byte for byte to a file in the jobs directory, and the block names it.
no example exercises it
rule.cancelStops line 50 · specs/runner/relay-job-type.sdp.md:50: Sending the message cancel to a running job stops it, also after the mod has reloaded.
no example exercises it
rule.resumeFromRunId line 51 · specs/runner/relay-job-type.sdp.md:51: A Workflow role that a resumed run finds finished returns its saved report without running again, and one it finds unfinished continues its saved Codex thread with a new turn, redoing the work that was in flight.
no example exercises it
rule.endedJobSurvivesReload line 52 · specs/runner/relay-job-type.sdp.md:52: After a reload, a job that had ended still returns the state block with its report.
no example exercises it

0 unkeyed rules.

Design

agentType line 56 · specs/runner/relay-job-type.sdp.md:56: cc-agents:job
no citation recorded
headerKeys line 57 · specs/runner/relay-job-type.sdp.md:57: backend, model, effort, mode, network, web-search, cd, add-dir, brief, fast, grok-home, kimi-home.
no citation recorded
backendProviders line 58 · specs/runner/relay-job-type.sdp.md:58: kimi on kimi-code-plan-global, grok on xai, zcode on zai-coding-plan, codex on Codex itself.
no citation recorded
stateBlockLines line 59 · specs/runner/relay-job-type.sdp.md:59: state: completed|cancelled|failed, job: <agent id>, backend: <backend>, model: <model>, effort: <effort>, mode: <mode>, duration: <time>, report: <path>, dir: <path>.
no citation recorded
jobsDirectory line 60 · specs/runner/relay-job-type.sdp.md:60: <state>/jobs/<agent id>/report.md.
no citation recorded
workflowMemory line 61 · specs/runner/relay-job-type.sdp.md:61: <state>/workflows/<run id>/<agent index>.json, written by the sidecar, read by /resume-lookup.
no citation recorded

Verification

Verifier bindings

test:cc-agents.mod-suite · the mod against a scripted sidecar · anchored · test anchor binding present · plugin/tests/mod.test.ts:4
test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · test anchor binding present · tests/sidecar.test.mjs:4

Design view

Requirement drawing

Declared verifying examples: no declared verifying example.

Requirement drawing for spec:cc-agents.relay-job-type

The diagram as text

spec:cc-agents.relay-job-type: The job agent takes Relay's header and returns Relay's state block · declared Spec
spec:cc-agents.runner: Other model families run as real Claude Code agents · declared Spec
impl:cc-agents.mod: answers each step of an agent from the sidecar's events, hands back the exact answer, steers and stops, and returns the job state block · anchored code · plugin/hooks/register.js:9
impl:cc-agents.relay-header: turns Relay's job header into a harness, a model and the turn's options · anchored code · plugin/sidecar/relay-header.mjs:9
impl:cc-agents.sidecar: the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · anchored code · plugin/sidecar/server.mjs:12
test:cc-agents.mod-suite: the mod against a scripted sidecar · anchored test binding · binding present · plugin/tests/mod.test.ts:4
test:cc-agents.sidecar-suite: the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored test binding · binding present · tests/sidecar.test.mjs:4
spec:cc-agents.relay-job-type refines spec:cc-agents.runner · declared
impl:cc-agents.mod satisfies spec:cc-agents.relay-job-type · anchored
impl:cc-agents.relay-header satisfies spec:cc-agents.relay-job-type · anchored
impl:cc-agents.sidecar satisfies spec:cc-agents.relay-job-type · anchored
test:cc-agents.mod-suite verifies spec:cc-agents.relay-job-type · anchored
test:cc-agents.sidecar-suite verifies spec:cc-agents.relay-job-type · anchored

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

Mermaid source for Requirement drawing for spec:cc-agents.relay-job-type

requirementDiagram
  requirement n0 {
    text: "The job agent takes Relay's header and returns Relay's state block · declared Spec · spec:cc-agents.relay-job-type"
  }
  element n1 {
    type: "answers each step of an agent from the sidecar's events, hands back the exact answer, steers and stops, and returns the job state block · anchored code · impl:cc-agents.mod"
  }
  element n2 {
    type: "turns Relay's job header into a harness, a model and the turn's options · anchored code · impl:cc-agents.relay-header"
  }
  element n3 {
    type: "the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · anchored code · impl:cc-agents.sidecar"
  }
  element n4 {
    type: "the mod against a scripted sidecar · anchored test binding · binding present · test:cc-agents.mod-suite"
  }
  element n5 {
    type: "the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored test binding · binding present · test:cc-agents.sidecar-suite"
  }
  requirement n6 {
    text: "Other model families run as real Claude Code agents · declared Spec · spec:cc-agents.runner"
  }
  %% claim: anchored
  n1 - satisfies -> n0
  %% claim: anchored
  n2 - satisfies -> n0
  %% claim: anchored
  n3 - satisfies -> n0
  %% claim: declared
  n0 - refines -> n6
  %% claim: anchored
  n4 - verifies -> n0
  %% claim: anchored
  n5 - verifies -> n0

Decisions

No decision record named.

Runtime

impl:cc-agents.mod · answers each step of an agent from the sidecar's events, hands back the exact answer, steers and stops, and returns the job state block · plugin/hooks/register.js:9
Uses
None.
impl:cc-agents.relay-header · turns Relay's job header into a harness, a model and the turn's options · plugin/sidecar/relay-header.mjs:9
Uses
None.
impl:cc-agents.sidecar · the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · plugin/sidecar/server.mjs:12
Uses
None.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact

Relations of spec:cc-agents.relay-job-type

The diagram as text

spec:cc-agents.hq-links: The one tie between this repository's Specs and HQ's design
spec:cc-agents.mod-layer: The mod answers an agent's steps from the sidecar and never calls a model
spec:cc-agents.relay-job-type: The job agent takes Relay's header and returns Relay's state block
spec:cc-agents.runner: Other model families run as real Claude Code agents
spec:cc-agents.sidecar: One sidecar per Claude session owns the session's harness turns
spec:cc-agents.relay-job-type dependsOn spec:cc-agents.mod-layer · declared — a job is an agent the mod spawns and steps like any other
spec:cc-agents.relay-job-type dependsOn spec:cc-agents.sidecar · declared — the header is translated, the report kept and the role remembered by the sidecar
spec:cc-agents.relay-job-type refines spec:cc-agents.runner · declared
spec:cc-agents.hq-links dependsOn spec:cc-agents.relay-job-type · declared — Relay's Workflow scripts move to the job runner by changing the agent type

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Mermaid source for Relations of spec:cc-agents.relay-job-type

flowchart TB
  n0["Other model families run as real Claude Code agents · spec:cc-agents.runner"]
  n1["The mod answers an agent's steps from the sidecar and never calls a model · spec:cc-agents.mod-layer"]
  n2["One sidecar per Claude session owns the session's harness turns · spec:cc-agents.sidecar"]
  n3["The job agent takes Relay's header and returns Relay's state block · spec:cc-agents.relay-job-type"]
  n4["The one tie between this repository's Specs and HQ's design · spec:cc-agents.hq-links"]
  n4 -->|"dependsOn · declared — Relay's Workflow scripts move to the job runner by changing the agent type"| n3
  n3 -->|"dependsOn · declared — a job is an agent the mod spawns and steps like any other"| n1
  n3 -->|"refines · declared"| n0
  n3 -->|"dependsOn · declared — the header is translated, the report kept and the role remembered by the sidecar"| n2

Rests on

refines · spec:cc-agents.runner · stated defined, floor ready
dependsOn · spec:cc-agents.mod-layer · stated ready, floor ready
dependsOn · spec:cc-agents.sidecar · stated ready, floor ready

Rested on by

Distance 1

spec:cc-agents.hq-links
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Relations

Relation and direction	Other end	Claim	Reason	Exercised keys
dependsOn · outgoing	The mod answers an agent's steps from the sidecar and never calls a model `spec:cc-agents.mod-layer` · resolves	declared	a job is an agent the mod spawns and steps like any other	None
dependsOn · outgoing	One sidecar per Claude session owns the session's harness turns `spec:cc-agents.sidecar` · resolves	declared	the header is translated, the report kept and the role remembered by the sidecar	None
refines · outgoing	Other model families run as real Claude Code agents `spec:cc-agents.runner` · resolves	declared	None	None
dependsOn · incoming	The one tie between this repository's Specs and HQ's design `spec:cc-agents.hq-links` · resolves	declared	Relay's Workflow scripts move to the job runner by changing the agent type	None

Bindings

Implementation binding: present

impl:cc-agents.mod · answers each step of an agent from the sidecar's events, hands back the exact answer, steers and stops, and returns the job state block · plugin/hooks/register.js:9
impl:cc-agents.relay-header · turns Relay's job header into a harness, a model and the turn's options · plugin/sidecar/relay-header.mjs:9
impl:cc-agents.sidecar · the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · plugin/sidecar/server.mjs:12

Design reference: none

Verifier binding: present

test:cc-agents.mod-suite · the mod against a scripted sidecar · anchored · plugin/tests/mod.test.ts:4 · test anchor
test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · tests/sidecar.test.mjs:4 · test anchor

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.