@openparachute/agent 0.2.3-rc.11 → 0.2.3-rc.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.11",
+  "version": "0.2.3-rc.12",
   "description": "Vault-native agents for Claude Code — a #agent/definition note + an inbound message becomes a sandboxed claude turn; the reply is written back as a note. Messaging gateway on :1941.",
   "license": "AGPL-3.0",
   "type": "module",

package/src/backends/programmatic.ts

@@ -442,6 +442,7 @@ export class ProgrammaticBackend implements AgentBackend {
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
     runContext?: RunContext,
+    subjectDossier?: string,
   ): Promise<DeliverResult> {
     const spec = handle.spec;
     if (!spec) {
@@ -587,10 +588,22 @@ export class ProgrammaticBackend implements AgentBackend {
     // Unset → no flag, no file (today's behavior unchanged). The `-file` form is
     // robust to long/multiline prompts and keeps the prompt visible-on-disk. Its
     // lifecycle is tied to the workspace (like .mcp.json) — it disappears with it.
+    //
+    // COMPOSED PROMPT (roles×threads NOW slice): when a `subjectDossier` is handed in,
+    // the agent's stable ROLE (the spec's systemPrompt) is composed with the per-thread
+    // subject context as `roleBody + "\n\n---\n\n" + dossier`. The role stays constant
+    // across a role's threads; the subject-specific dossier layers on top. Absent/empty
+    // dossier → the role body is written VERBATIM (byte-identical to HEAD — the
+    // null-subject invariant; the run-context preamble stays on the MESSAGE, not here).
     let systemPromptFile: string | undefined;
     if (typeof spec.systemPrompt === "string" && spec.systemPrompt.length > 0) {
+      const roleBody = spec.systemPrompt;
+      const composed =
+        typeof subjectDossier === "string" && subjectDossier.length > 0
+          ? `${roleBody}\n\n---\n\n${subjectDossier}`
+          : roleBody;
       systemPromptFile = join(workspace, "system-prompt.txt");
-      writeFileSync(systemPromptFile, spec.systemPrompt, { mode: 0o600 });
+      writeFileSync(systemPromptFile, composed, { mode: 0o600 });
     }
 
     // The agent's WORKING dir (design 2026-06-16-agent-filesystem-and-sharing.md):

package/src/backends/registry.ts

@@ -393,6 +393,16 @@ export interface QueuedMessage {
    * something else. Absent → the run context omits `fired-by`. Carries no routing meaning.
    */
   sender?: string;
+  /**
+   * The THREAD SUBJECT (roles×threads NOW slice) — rides from the inbound note's
+   * `metadata.subject`, through `contextFor.emit` (daemon.ts), onto this queue item.
+   * In the NOW slice it carries NO routing meaning — the drain stays per-CHANNEL serial,
+   * NOT per-subject — but it is threaded through so the composed prompt can fold in a
+   * subject dossier and the NEXT slice (#120 thread routing + per-thread session
+   * continuity) can key off it without re-plumbing. Absent → no subject (today's behavior;
+   * the weave path is untouched). Carries no routing meaning in NOW.
+   */
+  subject?: string;
 }
 
 /** A registered programmatic agent's live status (surfaced in /health + the list). */
@@ -478,6 +488,16 @@ export class ProgrammaticAgentRegistry {
    * Unwired → reset is a clean no-op beyond returning that the agent exists.
    */
   private readonly clearSession?: (channel: string, name: string) => Promise<void>;
+  /**
+   * Optional pre-turn SUBJECT-DOSSIER read (roles×threads NOW slice) — per-thread
+   * context for the current subject, folded into the composed system prompt (the
+   * programmatic backend's `roleBody + "\n\n---\n\n" + dossier`). Read in {@link drain}
+   * keyed on the inbound message's subject. UNWIRED in the NOW slice (the default registry
+   * does NOT set it — there's no dossier-note convention yet), so every turn composes the
+   * role body verbatim and the null-subject path is byte-identical to HEAD. The seam is
+   * here so a future dossier source threads in without re-plumbing `deliver`.
+   */
+  private readonly readSubjectDossier?: (channel: string, subject: string) => Promise<string | undefined>;
   /** Base backoff (ms) between outbound retries (FIX 1). Injectable so tests run fast. */
   private readonly outboundRetryBaseMs: number;
 
@@ -491,6 +511,11 @@ export class ProgrammaticAgentRegistry {
     readSession?: (channel: string, name: string) => Promise<string | undefined>;
     /** Clear the persisted thread-note session (the per-agent restart / reset). */
     clearSession?: (channel: string, name: string) => Promise<void>;
+    /**
+     * Read the per-thread subject dossier (roles×threads NOW slice). Optional + UNWIRED
+     * by default — the composed prompt is the role body verbatim until a dossier source exists.
+     */
+    readSubjectDossier?: (channel: string, subject: string) => Promise<string | undefined>;
     /** Override the outbound-retry backoff base (ms). Default {@link OUTBOUND_RETRY_BASE_MS}. */
     outboundRetryBaseMs?: number;
   }) {
@@ -501,6 +526,7 @@ export class ProgrammaticAgentRegistry {
     if (deps.onTurnEvent) this.onTurnEvent = deps.onTurnEvent;
     if (deps.readSession) this.readSession = deps.readSession;
     if (deps.clearSession) this.clearSession = deps.clearSession;
+    if (deps.readSubjectDossier) this.readSubjectDossier = deps.readSubjectDossier;
     this.outboundRetryBaseMs = deps.outboundRetryBaseMs ?? OUTBOUND_RETRY_BASE_MS;
   }
 
@@ -891,6 +917,24 @@ export class ProgrammaticAgentRegistry {
         ...(firedBy ? { firedBy } : {}),
       };
 
+      // SUBJECT DOSSIER (roles×threads NOW slice): when the inbound carries a subject AND a
+      // dossier source is wired, resolve the per-thread context the backend folds into the
+      // composed system prompt. UNWIRED by default (no dossier-note convention yet) and
+      // no-subject always → `undefined`, so the system prompt is the role body verbatim and
+      // the null-subject path is byte-identical to HEAD. Best-effort: a dossier read failure
+      // logs + the turn still runs (role-only), never strands the queue.
+      let subjectDossier: string | undefined;
+      if (msg.subject && this.readSubjectDossier) {
+        try {
+          subjectDossier = await this.readSubjectDossier(handle.channel, msg.subject);
+        } catch (err) {
+          console.error(
+            `parachute-agent: subject-dossier read for channel "${channel}" ` +
+              `subject "${msg.subject}" failed (turn runs role-only): ${(err as Error).message}`,
+          );
+        }
+      }
+
       let result;
       try {
         // Forward each interim event to the streaming-view sink (keyed by channel)
@@ -906,6 +950,9 @@ export class ProgrammaticAgentRegistry {
           msg.attachments,
           // agent#162: the daemon-known runtime context (real clock, new/resumed, fired-by).
           runContext,
+          // roles×threads NOW slice: the per-thread subject dossier, folded into the composed
+          // system prompt. Undefined (no subject / unwired source) → role body verbatim.
+          subjectDossier,
         );
       } catch (err) {
         // The backend contract is failure-as-VALUE, never a throw — but defend so a

package/src/backends/types.ts

@@ -244,6 +244,14 @@ export interface AgentBackend {
    * The programmatic backend prepends it as a concise, clearly-labeled preamble to the turn
    * message so the agent stamps ACCURATE times instead of fabricating them. ADDITIVE — omitted
    * → the turn message is exactly as before.
+   *
+   * `subjectDossier` (optional, roles×threads NOW slice) is per-THREAD context for the
+   * agent's CURRENT subject — folded into the SYSTEM prompt (NOT the message): the programmatic
+   * backend writes `roleBody + "\n\n---\n\n" + dossier` to the per-turn `system-prompt.txt` when
+   * present, so the agent's ROLE (the spec's systemPrompt) stays stable across threads while the
+   * subject-specific context layers on top. The run-context preamble is unaffected (it stays on
+   * the MESSAGE). ADDITIVE — omitted/empty → the system prompt is the role body verbatim
+   * (byte-identical to HEAD; the null-subject invariant).
    */
   deliver(
     handle: AgentHandle,
@@ -252,6 +260,7 @@ export interface AgentBackend {
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
     runContext?: RunContext,
+    subjectDossier?: string,
   ): Promise<DeliverResult>;
 
   /**

package/src/daemon.ts

@@ -345,6 +345,10 @@ export function contextFor(
           // agent#162: carry the inbound sender so the drain can derive the run-context
           // `fired-by` (a scheduled `runner:<jobId>` fire vs an interactive/delegated message).
           ...(msg.meta?.sender ? { sender: msg.meta.sender } : {}),
+          // roles×threads NOW slice: carry the thread subject through to the drain so the
+          // composed prompt can fold in a subject dossier (and the NEXT slice can route by
+          // it). No routing meaning yet. Absent → unchanged (the weave path is untouched).
+          ...(msg.meta?.subject ? { subject: msg.meta.subject } : {}),
         });
         return;
       }
@@ -372,6 +376,10 @@ export function contextFor(
           // agent#162: carry the sender through the pending buffer too, so a turn that runs on
           // register() still derives the right run-context `fired-by`.
           ...(msg.meta?.sender ? { sender: msg.meta.sender } : {}),
+          // roles×threads NOW slice: carry the thread subject through the pending buffer too,
+          // so a turn that runs on register() still folds in its subject dossier. No routing
+          // meaning yet. Absent → unchanged.
+          ...(msg.meta?.subject ? { subject: msg.meta.subject } : {}),
         });
         if (outcome === "queued") return;
         // outcome === "unknown" — not an expected programmatic channel. It may still be a
@@ -1815,7 +1823,12 @@ export function createFetchHandler(
           if (!transport) {
             return json({ error: `job "${id}" targets a non-vault channel "${job.channel}"` }, 400);
           }
-          await transport.injectInbound({ content: job.message, sender: `runner:${job.id}` });
+          // roles×threads NOW slice: thread the job's subject (absent → no subject).
+          await transport.injectInbound({
+            content: job.message,
+            sender: `runner:${job.id}`,
+            ...(job.subject ? { subject: job.subject } : {}),
+          });
           return json({ ok: true, id, status: "ok" });
         } catch (err) {
           return json({ error: `failed to run job: ${(err as Error).message}` }, 502);
@@ -3381,7 +3394,14 @@ function main(): void {
       if (!transport) {
         throw new Error(`channel "${job.channel}" is not a live vault channel`);
       }
-      await transport.injectInbound({ content: job.message, sender: `runner:${job.id}` });
+      // roles×threads NOW slice: thread the job's subject onto the inbound note so the
+      // turn's composed prompt can fold in its dossier. Absent → no subject (the weave
+      // job carries none → byte-identical to HEAD).
+      await transport.injectInbound({
+        content: job.message,
+        sender: `runner:${job.id}`,
+        ...(job.subject ? { subject: job.subject } : {}),
+      });
     },
     // Persist bookkeeping (lastRunAt/lastStatus) back onto the job note (addressed
     // by its vault note id). A job loaded from the store always carries `noteId`.

package/src/jobs.ts

@@ -65,6 +65,13 @@ export interface Job {
   lastStatus?: string;
   /** ISO timestamp of the next scheduled fire — COMPUTED IN MEMORY, never persisted. */
   nextRunAt?: string;
+  /**
+   * The THREAD SUBJECT a fire of this job carries (roles×threads NOW slice). When set,
+   * the runner stamps it onto the inbound note (`metadata.subject`) so the turn's composed
+   * prompt + (NEXT) thread routing can read it. Optional; absent → today's behavior (the
+   * weave job carries none — its fire is byte-identical to HEAD).
+   */
+  subject?: string;
 }
 
 /** A slug: alphanumeric, dash, underscore (same shape as channel names). */
@@ -202,6 +209,7 @@ export class VaultJobStore {
           createdAt: n.createdAt ?? "",
           ...(n.lastRunAt ? { lastRunAt: n.lastRunAt } : {}),
           ...(n.lastStatus ? { lastStatus: n.lastStatus } : {}),
+          ...(n.subject ? { subject: n.subject } : {}),
         });
       }
     }
@@ -229,6 +237,7 @@ export class VaultJobStore {
       createdAt: job.createdAt,
       ...(job.lastRunAt ? { lastRunAt: job.lastRunAt } : {}),
       ...(job.lastStatus ? { lastStatus: job.lastStatus } : {}),
+      ...(job.subject ? { subject: job.subject } : {}),
     });
     return { ...job, noteId }; // id stays the slug; noteId addresses the persisted note.
   }

package/src/sandbox/types.ts

@@ -380,3 +380,41 @@ export function normalizeChannel(ch: AgentChannel): { name: string; access: "rea
   if (typeof ch === "string") return { name: ch, access: "write" };
   return { name: ch.name, access: ch.access ?? "write" };
 }
+
+/**
+ * Collapse a string to a flat, path-safe slug — every char outside
+ * `[a-zA-Z0-9_-]` becomes `-`. This MIRRORS the channel/name sanitizer used on
+ * the vault note paths (`vault.ts:746`, `:822-823`) so a value sanitized here
+ * can be used as a path leaf or a `--session-id` segment without re-escaping.
+ * Pure + idempotent. Exported so the NEXT slice (per-thread workspace paths,
+ * spec §G) reuses this exact sanitizer rather than re-implementing it (drift risk).
+ */
+export function slug(raw: string): string {
+  return raw.replace(/[^a-zA-Z0-9_-]/g, "-");
+}
+
+/**
+ * The THREAD identity key for one (agent, subject) pair — the roles×threads NOW
+ * slice (design team-vault `Strategy/2026-06-29-agents-roles-threads`).
+ *
+ *  - No subject (absent / empty / whitespace-only) → the BARE `specName`. This is
+ *    the back-compat path: every agent today (incl. the weave) carries no subject,
+ *    so `threadKey` returns exactly the spec name and every downstream
+ *    path/key/workspace is byte-identical to HEAD.
+ *  - A non-empty subject → `${specName}--${slug(subject)}`. The `--` separator and
+ *    the `slug()` sanitize make the key safe to use as a vault path leaf or a
+ *    Claude `--session-id` segment.
+ *
+ * SECURITY: `subject` is UNTRUSTED input that later becomes a path leaf, so it is
+ * run through {@link slug} here — `../`, spaces, slashes, and other path-dangerous
+ * chars collapse to `-`, so a subject can never traverse the path hierarchy.
+ * `specName` is NOT sanitized here (it's already a sanitized agent/channel name
+ * upstream); only the untrusted subject is.
+ *
+ * NOTE: subject is PER-THREAD — it rides on the inbound message, NOT on the
+ * {@link AgentSpec} (which is per-AGENT). Keep it off the spec.
+ */
+export function threadKey(specName: string, subject?: string): string {
+  const trimmed = subject?.trim();
+  return trimmed ? `${specName}--${slug(trimmed)}` : specName;
+}

package/src/transports/vault.ts

@@ -161,6 +161,11 @@ export interface JobNote {
   lastRunAt?: string;
   /** "ok" / "error: …" from the most recent fire. */
   lastStatus?: string;
+  /**
+   * The THREAD SUBJECT a fire carries (roles×threads NOW slice) — read back from
+   * `metadata.subject`. Optional; absent → today's behavior (no subject).
+   */
+  subject?: string;
 }
 
 /** The metadata payload written for a job note (all string-typed, per the vault). */
@@ -176,6 +181,13 @@ export interface JobNoteMetadata {
   createdAt: string;
   lastRunAt?: string;
   lastStatus?: string;
+  /**
+   * The THREAD SUBJECT a fire of this job carries (roles×threads NOW slice) — stamped
+   * onto the inbound note the runner injects, so the turn's composed prompt + (NEXT)
+   * thread routing can read it. Optional; absent → today's behavior (the weave job
+   * carries none).
+   */
+  subject?: string;
 }
 
 /**
@@ -1319,8 +1331,21 @@ export class VaultTransport implements Transport {
    * thin wrapper over `writeInbound` so the inbound write path has ONE
    * implementation; only the default sender differs.
    */
-  async injectInbound(opts: { content: string; sender?: string }): Promise<{ id: string }> {
-    return this.writeInbound(opts.content, opts.sender ?? "runner");
+  async injectInbound(opts: {
+    content: string;
+    sender?: string;
+    /**
+     * SUBJECT (roles×threads NOW slice) — the thread axis for a runner-fired turn.
+     * When a job carries a subject, the runner threads it here; it's stamped onto the
+     * inbound note's `metadata.subject` (via {@link writeInbound}'s `extraMeta`) so the
+     * turn's composed prompt + (NEXT) thread routing can read it. Absent/empty → NO
+     * `subject` field on the note (today's behavior exactly — the weave job is unaffected).
+     */
+    subject?: string;
+  }): Promise<{ id: string }> {
+    const subject = opts.subject?.trim();
+    const extraMeta = subject ? { subject } : undefined;
+    return this.writeInbound(opts.content, opts.sender ?? "runner", extraMeta);
   }
 
   /**
@@ -1579,6 +1604,10 @@ export class VaultTransport implements Transport {
       if (typeof m.createdAt === "string") job.createdAt = m.createdAt;
       if (typeof m.lastRunAt === "string") job.lastRunAt = m.lastRunAt;
       if (typeof m.lastStatus === "string") job.lastStatus = m.lastStatus;
+      // roles×threads NOW slice: read the thread subject back (absent/blank → undefined).
+      // Trim-guarded symmetrically with the write side (upsertJobNote) so a whitespace-only
+      // value that somehow landed in the vault can't propagate downstream as a "subject".
+      if (typeof m.subject === "string" && m.subject.trim()) job.subject = m.subject.trim();
       jobs.push(job);
     }
     return jobs;
@@ -1600,6 +1629,8 @@ export class VaultTransport implements Transport {
     createdAt: string;
     lastRunAt?: string;
     lastStatus?: string;
+    /** The thread subject a fire carries (roles×threads NOW slice); absent → no field. */
+    subject?: string;
   }): Promise<{ id: string }> {
     const safeId = job.id.replace(/[^a-zA-Z0-9_-]/g, "-");
     const safeChannel = job.channel.replace(/[^a-zA-Z0-9_-]/g, "-");
@@ -1615,6 +1646,11 @@ export class VaultTransport implements Transport {
     if (job.tz) metadata.tz = job.tz;
     if (job.lastRunAt) metadata.lastRunAt = job.lastRunAt;
     if (job.lastStatus) metadata.lastStatus = job.lastStatus;
+    // roles×threads NOW slice: persist a non-empty subject; absent → no field (the weave
+    // job writes none, so its note is byte-identical to HEAD).
+    if (typeof job.subject === "string" && job.subject.trim().length > 0) {
+      metadata.subject = job.subject.trim();
+    }
 
     const res = await fetch(`${this.vaultUrl}/vault/${this.vault}/api/notes`, {
       method: "POST",
@@ -1772,9 +1808,13 @@ export class VaultTransport implements Transport {
     }
     // Flatten the note's metadata into the inbound meta (string-valued), then
     // stamp our own provenance fields. `source`/`note_id`/`direction` are set
-    // explicitly so they win over anything in the note's metadata.
+    // explicitly so they win over anything in the note's metadata. `subject` is
+    // SKIPPED here and handled explicitly below (normalized to non-empty-or-absent),
+    // so a blank `subject: "   "` can't slip through the raw spread — absent and
+    // whitespace-only must be indistinguishable downstream (the null-subject invariant).
     const flatMeta: Record<string, string> = {};
     for (const [k, v] of Object.entries(meta)) {
+      if (k === "subject") continue;
       flatMeta[k] = typeof v === "string" ? v : String(v);
     }
 
@@ -1789,6 +1829,18 @@ export class VaultTransport implements Transport {
       attachments = await this.fetchInboundAttachments(note.id);
     }
 
+    // SUBJECT (roles×threads NOW slice). The thread axis: when the inbound note
+    // carries a non-empty string `metadata.subject`, surface it onto the emitted
+    // event meta so it can flow through the queue → composed prompt → (NEXT) thread
+    // routing. ABSENT/empty → no `subject` field on the emitted meta, so the emit is
+    // BYTE-IDENTICAL to HEAD (the null-subject invariant — the weave path is untouched).
+    // `subject` is deliberately SKIPPED in the `flatMeta` spread above and re-added here
+    // ONLY when non-empty, so an empty/whitespace-only value can never leak through —
+    // absent and blank are indistinguishable downstream.
+    const rawSubject = meta.subject;
+    const subject =
+      typeof rawSubject === "string" && rawSubject.trim().length > 0 ? rawSubject : undefined;
+
     this.ctx.emit({
       // `channel` here is the in-memory InboundMessage.channel TS field (NOT serialized
       // note metadata) — left as the channel name. The routing key rides in `meta.agent`.
@@ -1803,6 +1855,7 @@ export class VaultTransport implements Transport {
         note_id: note.id,
         sender: typeof meta.sender === "string" ? meta.sender : "",
         direction: "inbound",
+        ...(subject ? { subject } : {}),
       },
       source: "vault",
       ...(attachments.length > 0 ? { attachments } : {}),