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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.10",
+  "version": "0.2.3-rc.11",
   "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

@@ -85,6 +85,7 @@ import type {
   DeliverResult,
   DeliverUsage,
   InterimSink,
+  RunContext,
   TurnSession,
 } from "./types.ts";
 
@@ -327,6 +328,32 @@ export function buildProgrammaticClaudeArgs(opts: {
   return argv;
 }
 
+/**
+ * Render the {@link RunContext} as a concise, clearly-LABELED preamble to PREPEND to a turn's
+ * message (agent#162). A headless `claude -p` turn has no clock + no notion of which run it is,
+ * so the daemon hands it these facts (the real wall-clock, new-vs-resumed, why it fired, the
+ * prior turn count) — the agent then stamps ACCURATE times instead of fabricating them.
+ *
+ * It is a single fenced block clearly marked as daemon-injected runtime context (NOT the
+ * agent's own system prompt — that's untouched), then a blank line, then the real message. The
+ * `now` is always present; the rest are appended only when known. Returns the message UNCHANGED
+ * when `rc` is absent (additive — no behavior change for a caller that doesn't pass one).
+ */
+export function renderRunContext(message: string, rc: RunContext | undefined): string {
+  if (!rc) return message;
+  const parts: string[] = [`now=${rc.now}`, `session=${rc.session}`];
+  if (typeof rc.priorTurnCount === "number" && rc.priorTurnCount >= 0) {
+    // The NUMBER of this turn (1-based) = completed turns + 1 — what an agent stamps as "turn N".
+    parts.push(`turn=${rc.priorTurnCount + 1}`);
+  }
+  if (rc.firedBy) parts.push(`fired-by=${rc.firedBy}`);
+  const preamble =
+    `[Run context — injected by the agent daemon (this is the real runtime state, NOT your ` +
+    `system prompt). Use these for any timestamp/clock or "which run is this" reasoning instead ` +
+    `of guessing: ${parts.join(", ")}]`;
+  return `${preamble}\n\n${message}`;
+}
+
 /** Read the full text of a (possibly null) byte stream; null/error → "". */
 async function drainStream(stream: ReadableStream<Uint8Array> | null): Promise<string> {
   if (!stream) return "";
@@ -414,6 +441,7 @@ export class ProgrammaticBackend implements AgentBackend {
     session: TurnSession,
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
+    runContext?: RunContext,
   ): Promise<DeliverResult> {
     const spec = handle.spec;
     if (!spec) {
@@ -537,13 +565,18 @@ export class ProgrammaticBackend implements AgentBackend {
     // per-agent even when the working dir is shared. Best-effort + isolated: a single
     // attachment's fetch/stage failure logs + is SKIPPED (the turn still runs with the rest
     // + the text). Absent/empty → no staging, no prompt change (today's behavior exactly).
-    let turnMessage = message;
+    // RUN CONTEXT (agent#162): prepend the daemon-injected runtime preamble (the real
+    // wall-clock + new/resumed + why-it-fired) so the headless turn reads ACCURATE facts
+    // instead of fabricating a clock. Done FIRST so the preamble sits at the very top of the
+    // prompt; attachments append after the (already-prefixed) message. Absent runContext →
+    // the message is unchanged (additive).
+    let turnMessage = renderRunContext(message, runContext);
     if (attachments && attachments.length > 0) {
       const staged = await this.stageAttachments(workspace, attachments, vaultArg);
       if (staged.length > 0) {
         const lines = staged.map((s) => `- ${s.absPath} (${s.mimeType})`);
         turnMessage =
-          `${message}\n\n[Attached files — read them as needed:\n${lines.join("\n")}\n]`;
+          `${turnMessage}\n\n[Attached files — read them as needed:\n${lines.join("\n")}\n]`;
       }
     }
 

package/src/backends/registry.ts

@@ -44,7 +44,7 @@
 
 import type { AgentSpec, AgentMode } from "../sandbox/types.ts";
 import { normalizeChannel } from "../sandbox/types.ts";
-import type { AgentBackend, AgentHandle, InterimTurnEvent, TurnSession } from "./types.ts";
+import type { AgentBackend, AgentHandle, InterimTurnEvent, RunContext, TurnSession } from "./types.ts";
 import type { InboundAttachment } from "../transport.ts";
 
 /**
@@ -90,12 +90,15 @@ export type WriteOutbound = (
   reply: string,
   inReplyTo?: string,
   /**
-   * The per-turn thread id this reply belongs to — the explicit definition→thread→message
-   * link the outbound note carries (stamped into `metadata.thread`). For multi-threaded it
-   * IS the per-fire thread note's leaf (an exact link); for single-threaded it's a per-turn
-   * correlation id (the note's stable deterministic leaf is the def name — single-threaded
-   * outbound→note linkage by the stable path is a follow-up). INBOUND-note stamping is
-   * deferred (those notes are externally written; see the PR notes).
+   * The RESOLVABLE, MODE-CORRECT thread id this reply belongs to — the explicit
+   * definition→thread→message link the outbound note carries (stamped into `metadata.thread`),
+   * mirroring the callback `source_thread` fix (agent#124/#163). For multi-threaded it IS the
+   * per-fire thread note's leaf (`Threads/<channel>/<id>`); for single-threaded it is the
+   * DETERMINISTIC thread-NOTE id (`Threads/<channel>/<name>`), STABLE across turns — so an
+   * observer reading the outbound note's `metadata.thread` resolves the agent's ONE thread
+   * with `query-notes { id }`, instead of the per-turn correlation UUID that changed every
+   * run (the pre-#163 bug that looked like a fresh session each time). INBOUND-note stamping
+   * is deferred (those notes are externally written; see the PR notes).
    */
   threadId?: string,
 ) => Promise<{ id?: string } | void>;
@@ -302,6 +305,46 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * The thread id to stamp into an OUTBOUND note's `metadata.thread` (agent#163) — the
+ * MODE-CORRECT, RESOLVABLE definition→thread→message link, mirroring the callback
+ * `source_thread` fix (agent#124):
+ *
+ *  - SINGLE-THREADED — the resolvable thread-NOTE id (the deterministic
+ *    `Threads/<safeChannel>/<safeName>` note), so an observer reading the outbound note's
+ *    `metadata.thread` resolves the agent's ONE stable thread with `query-notes { id }`.
+ *    The pre-#163 bug stamped the per-turn correlation UUID here, which changed every turn
+ *    and resolved to nothing — misleading an observer into "a fresh session each run" when
+ *    the single-threaded session is actually stable + resumed across turns.
+ *  - MULTI-THREADED — the per-fire id (`turnThreadId`), which IS that fire's thread-note leaf
+ *    (`Threads/<safeChannel>/<turnThreadId>`) — correct as-is: each fire is its own thread.
+ *
+ * Falls back to `turnThreadId` when no resolvable note id surfaced (no durable thread store
+ * wired, or the thread-note write failed) — never undefined, so the link is always stamped.
+ */
+export function outboundThreadId(
+  multiThreaded: boolean,
+  turnThreadId: string,
+  threadNoteId: string | undefined,
+): string {
+  if (multiThreaded) return turnThreadId;
+  return threadNoteId ?? turnThreadId;
+}
+
+/**
+ * Derive the run-context `fired-by` provenance (agent#162) from an inbound message's
+ * `sender` (the note's `metadata.sender`). A SCHEDULED job fire stamps `runner:<jobId>`
+ * (the runner's sender provenance) → reported as the job id so the agent knows it's a cron
+ * fire; anything else (a human / a delegated agent message) → `interactive`. Absent sender →
+ * undefined (the run context omits `fired-by`).
+ */
+export function runFiredBy(sender: string | undefined): string | undefined {
+  if (!sender) return undefined;
+  const m = /^runner:(.+)$/.exec(sender);
+  if (m) return `scheduled-job:${m[1]}`;
+  return "interactive";
+}
+
 /** A queued inbound message awaiting its serial turn. */
 export interface QueuedMessage {
   /** The inbound text handed to the `claude -p` turn as the prompt. */
@@ -343,6 +386,13 @@ export interface QueuedMessage {
    * `Read` it. Absent/empty → no attachments (today's behavior unchanged).
    */
   attachments?: InboundAttachment[];
+  /**
+   * WHO/WHAT sent this inbound (the note's `metadata.sender`) — used ONLY to derive the
+   * run-context `fired-by` provenance the daemon injects into the turn (agent#162): a
+   * SCHEDULED job fire stamps `runner:<jobId>`, an interactive/delegated message stamps
+   * something else. Absent → the run context omits `fired-by`. Carries no routing meaning.
+   */
+  sender?: string;
 }
 
 /** A registered programmatic agent's live status (surfaced in /health + the list). */
@@ -806,7 +856,11 @@ export class ProgrammaticAgentRegistry {
       // start+end never double-count. Best-effort: a start-ensure write failure is logged
       // (inside recordThread) and the turn STILL runs — a missing/stale working note must
       // never strand the queue or skip the turn.
-      await this.recordThread(handle, msg, "working", "", startedAt, undefined, {
+      // Capture the start-ensure's WRITTEN thread-note id. For single-threaded this is the
+      // DETERMINISTIC `Threads/<safeChannel>/<safeName>` note (the same every turn) — so a
+      // resolvable thread id is available BEFORE the turn runs, for the failure-note +
+      // outbound `metadata.thread` stamping (agent#163), even on a turn that fails early.
+      const startThreadNoteId = await this.recordThread(handle, msg, "working", "", startedAt, undefined, {
         threadId: turnThreadId,
         phase: "start",
         // NO session on the start-ensure: it runs BEFORE claude, so claude may never
@@ -816,6 +870,26 @@ export class ProgrammaticAgentRegistry {
         // the `end` record, and ONLY the id claude actually echoed (FIX 2). For a
         // single-threaded resume turn the prior session is preserved by writeThread anyway.
       });
+      // The MODE-CORRECT, RESOLVABLE thread id stamped into outbound + failure notes
+      // (agent#163): single-threaded → the deterministic thread-NOTE id (stable across turns);
+      // multi-threaded → the per-fire `turnThreadId`. Computed once from the start-ensure id so
+      // every path (early failure, ok, outbound-failure) stamps the same resolvable link.
+      const outThreadId = outboundThreadId(multiThreaded, turnThreadId, startThreadNoteId);
+
+      // RUN CONTEXT (agent#162): assemble the runtime facts a headless `claude -p` turn can't
+      // know — the REAL wall-clock (`startedAt`), whether this run CONTINUES a prior session
+      // (`turnSession.resume`) or starts fresh, and WHY it fired (a scheduled job vs an
+      // interactive/delegated message, from the inbound sender). The backend prepends these as
+      // a labeled preamble so the agent stamps ACCURATE times instead of fabricating them.
+      // (DEFERRED: `priorTurnCount` — the rolling turn_count lives in the transport's thread
+      // note and isn't surfaced back to the drain; wiring it is a follow-up. Until then the
+      // preamble omits the `turn=N` line — the `now`/session/fired-by trio is the floor.)
+      const firedBy = runFiredBy(msg.sender);
+      const runContext: RunContext = {
+        now: startedAt,
+        session: turnSession.resume ? "resumed" : "new",
+        ...(firedBy ? { firedBy } : {}),
+      };
 
       let result;
       try {
@@ -830,6 +904,8 @@ export class ProgrammaticAgentRegistry {
           // Phase 1: inbound attachments → the programmatic backend stages them into the
           // agent's private workspace so the turn can Read them. Absent/empty → no staging.
           msg.attachments,
+          // agent#162: the daemon-known runtime context (real clock, new/resumed, fired-by).
+          runContext,
         );
       } catch (err) {
         // The backend contract is failure-as-VALUE, never a throw — but defend so a
@@ -854,8 +930,8 @@ export class ProgrammaticAgentRegistry {
         });
         this.emitTurnEvent(channel, { kind: "error", error: reason });
         // Post a user-facing failure note so the channel shows SOMETHING (not a silent
-        // no-reply) — best-effort.
-        await this.postFailureNote(channel, msg.inReplyTo, turnThreadId, reason);
+        // no-reply) — best-effort. Stamp the MODE-CORRECT resolvable thread id (agent#163).
+        await this.postFailureNote(channel, msg.inReplyTo, outThreadId, reason);
         // CALLBACK on the failure too — an orchestrator MUST learn its sub-task failed, not
         // hang waiting forever. No outbound note was produced, so no `source_message`; the
         // RESOLVABLE thread-note id (written above) is `source_thread` so the orchestrator can
@@ -886,8 +962,8 @@ export class ProgrammaticAgentRegistry {
         });
         this.emitTurnEvent(channel, { kind: "error", error: result.error });
         // Post a user-facing failure note so the channel shows SOMETHING (not a silent
-        // no-reply) — best-effort.
-        await this.postFailureNote(channel, msg.inReplyTo, turnThreadId, result.error);
+        // no-reply) — best-effort. Stamp the MODE-CORRECT resolvable thread id (agent#163).
+        await this.postFailureNote(channel, msg.inReplyTo, outThreadId, result.error);
         // CALLBACK on the failure-as-value too (status:error) — the orchestrator learns the
         // sub-task failed and can react. No delivered reply, so no `source_message`; the
         // RESOLVABLE thread-note id (written above) is `source_thread` (agent#124).
@@ -931,7 +1007,12 @@ export class ProgrammaticAgentRegistry {
           channel,
           result.reply,
           msg.inReplyTo,
-          turnThreadId,
+          // agent#163: stamp the MODE-CORRECT, RESOLVABLE thread id into the outbound note's
+          // `metadata.thread` — single-threaded → the deterministic thread-NOTE id (stable
+          // across turns; an observer resolves the ONE thread), multi-threaded → the per-fire
+          // id. NOT the per-turn correlation UUID (the pre-#163 bug that looked like a fresh
+          // session every run).
+          outThreadId,
         );
         if (delivered.ok) sourceMessage = delivered.noteId;
         if (!delivered.ok) {

package/src/backends/types.ts

@@ -84,6 +84,43 @@ export interface TurnSession {
   resume: boolean;
 }
 
+/**
+ * RUN CONTEXT for one turn (agent#162) — the runtime facts a programmatic `claude -p` turn
+ * otherwise has NO way to know, so an agent stops FABRICATING them. A headless `-p` turn has
+ * no clock and no notion of "which run this is": uni-weaver was openly inventing report
+ * timestamps (a fixed `10:05` slot, the date "derived from context") because it couldn't read
+ * a real clock mid-run. The daemon KNOWS these facts at dispatch time, so it injects them into
+ * the turn (a concise, clearly-labeled preamble the agent reads) rather than letting the agent
+ * guess. Cheap, and it removes a whole class of fabricated-time confusion.
+ *
+ * The backend renders this as a SHORT preamble prepended to the turn message — it never
+ * mangles the agent's own system-prompt semantics. ADDITIVE: a caller that omits it leaves the
+ * turn message exactly as before.
+ */
+export interface RunContext {
+  /** The REAL wall-clock at dispatch (ISO 8601) — the authoritative clock the turn lacks. */
+  now: string;
+  /**
+   * Whether this turn CONTINUES a prior conversation (`resumed`, single-threaded turn 2+) or
+   * STARTS a fresh one (`new`, the first turn / every multi-threaded fire) — the cheap "which
+   * run is this" signal the daemon already resolved (`TurnSession.resume`).
+   */
+  session: "new" | "resumed";
+  /**
+   * WHY this turn is running (provenance): a SCHEDULED job fire stamps `runner:<jobId>` (the
+   * runner's sender provenance) → reported as the job id; anything else is an interactive /
+   * delegated message → `interactive`. Lets a scheduled agent know it's a cron fire vs a live
+   * reply. Absent when the inbound carried no sender.
+   */
+  firedBy?: string;
+  /**
+   * The thread's COMPLETED turn count BEFORE this turn (single-threaded's rolling counter;
+   * 0 on the first turn). Best-effort — omitted when the daemon can't cheaply resolve it
+   * (no durable thread store). So the agent can stamp "turn N" accurately.
+   */
+  priorTurnCount?: number;
+}
+
 /**
  * An opaque handle to a started agent, returned by {@link AgentBackend.start} and
  * passed back to `deliver`/`stop`/`status`. The only field the seam itself depends
@@ -201,6 +238,12 @@ export interface AgentBackend {
    * a safe basename) before the turn and appends a workspace-relative pointer to the
    * prompt, so the `claude -p` turn can `Read` them. ADDITIVE — absent/empty → no
    * staging, the turn behaves exactly as before.
+   *
+   * `runContext` (optional, agent#162) is the runtime context the daemon knows but a headless
+   * `-p` turn can't (the real wall-clock, whether this run is new vs resumed, why it fired).
+   * 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.
    */
   deliver(
     handle: AgentHandle,
@@ -208,6 +251,7 @@ export interface AgentBackend {
     session: TurnSession,
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
+    runContext?: RunContext,
   ): Promise<DeliverResult>;
 
   /**

package/src/daemon.ts

@@ -342,6 +342,9 @@ export function contextFor(
           // Phase 1: carry inbound file attachments through to the turn (the programmatic
           // backend stages them into the agent's private workspace so the turn can Read them).
           ...(msg.attachments && msg.attachments.length > 0 ? { attachments: msg.attachments } : {}),
+          // 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 } : {}),
         });
         return;
       }
@@ -366,6 +369,9 @@ export function contextFor(
           // Phase 1: carry inbound attachments through the pending buffer too, so a turn
           // that runs on register() still stages them.
           ...(msg.attachments && msg.attachments.length > 0 ? { attachments: msg.attachments } : {}),
+          // 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 } : {}),
         });
         if (outcome === "queued") return;
         // outcome === "unknown" — not an expected programmatic channel. It may still be a

package/src/transports/vault.ts

@@ -761,11 +761,14 @@ export class VaultTransport implements Transport {
     // Thread the reply to the inbound note id when the bridge passes it through.
     const inReplyTo = args.meta?.in_reply_to;
     if (inReplyTo) metadata.in_reply_to = inReplyTo;
-    // The explicit definition→thread→message link: stamp the outbound note with its thread
-    // id (the programmatic worker passes the per-turn thread id through `meta.thread`). For a
-    // multi-threaded turn this IS the per-fire `#agent/thread` note's leaf; for a
-    // single-threaded turn it's a per-turn correlation id. INBOUND-note stamping is deferred
-    // (those notes are written externally, before the turn knows its thread).
+    // The explicit definition→thread→message link: stamp the outbound note with its
+    // RESOLVABLE, mode-correct thread id (the programmatic worker passes it through
+    // `meta.thread`, agent#163). For a multi-threaded turn this IS the per-fire `#agent/thread`
+    // note's leaf; for a single-threaded turn it's the DETERMINISTIC thread-NOTE id
+    // (`Threads/<channel>/<name>`), STABLE across turns — so an observer resolves the agent's
+    // ONE thread from `metadata.thread`, not a per-turn UUID that changed every run.
+    // INBOUND-note stamping is deferred (those notes are written externally, before the turn
+    // knows its thread).
     const threadId = args.meta?.thread;
     if (threadId) metadata.thread = threadId;