@miadi/connector 0.1.19 → 0.1.21

package/dist/steer.js

@@ -6,9 +6,13 @@
  * - The target is the pane the mission is bound to — the pane the grant names,
  *   else the session's first pane (lowest window, lowest pane, jgwill/Miadi#725).
  *   The active pane plays no part.
- * - peek → scoped act → re-peek (jgwill/Miadi#345): visible pasted text is not
- *   acceptance; acceptance is the pane recaptured and the agent seen
- *   processing, with the instruction scrolled out of the input line.
+ * - A working agent is the normal case (jgwill/Miadi#930). With a runtime route, the correction
+ *   goes to that session's own inbox and the runtime decides when its model reads it
+ *   (runtime-steer.ts). Without one, a busy seat answers unsupported with the reason; nothing
+ *   is typed into a working agent's pane.
+ * - An idle seat has no continuation coming, so it is the one case still typed, into its bound
+ *   pane: peek → scoped act → re-peek (jgwill/Miadi#345). A pane echo is not acceptance; what
+ *   reached the model is read from the transcript (readSteerDelivery).
  * - Every attempt leaves a durable artifact: the instruction, its sha256, the
  *   grant it ran under, the target, the timestamps and both captures.
  * - Pane content is evidence, never instruction: nothing an agent printed is
@@ -16,8 +20,9 @@
  */
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { enqueueSteer, resolveRuntime, sameInstructionInFlight, transcriptPathOf } from "./runtime-steer.js";
 export const STEER_STATUSES = [
     "prepared",
     "submitted",
@@ -29,6 +34,9 @@ export const STEER_STATUSES = [
     "expired_grant",
     "duplicate",
     "composing",
+    // jgwill/Miadi#930. "busy" stays readable on old records; a new steer never answers it.
+    "queued_at_runtime",
+    "unsupported",
 ];
 /** Commands that mark a pane as an agent seat a steer may land in. */
 export const AGENT_COMMANDS = ["claude", "codex", "copilot", "pi", "gemini", "node"];
@@ -121,20 +129,26 @@ export function steeringGrantOf(run) {
     };
 }
 /** Whether a grant covers one more steer. `priorAttempts` counts the steers already run under it. */
-export function checkGrant(grant, priorAttempts, now = new Date()) {
+export function checkGrant(grant, priorAttempts, now = new Date(), revoked = false) {
     if (!grant)
         return "no_grant";
+    if (revoked)
+        return "revoked";
     if (grant.expires_at && !Number.isNaN(Date.parse(grant.expires_at)) && Date.parse(grant.expires_at) <= now.getTime())
         return "expired_grant";
     if ((grant.max_attempts ?? 0) <= priorAttempts)
         return "duplicate";
     return "ok";
 }
+/** Whether a person revoked this run's steering, or just this one steer when `steer` is given (jgwill/Miadi#930). */
+export function steeringRevoked(records, grantId) {
+    return records.some((r) => r.kind === "steering_revocation" && r.refs.includes(grantId) && !r.body.steer);
+}
 /**
  * Steers already run under a grant: decided (or grant-covered) steer records that cite it and
- * typed their instruction (jgwill/Miadi#909). A steer stopped before typing (busy, composing,
- * wrong or stale pane, transport down) uses none of the grant's attempts. Receipts made before
- * `typed` was recorded count when their outcome says the text was delivered.
+ * typed or forwarded their instruction (jgwill/Miadi#909, #930). A steer stopped before that
+ * (composing, unsupported, wrong or stale pane, transport down) uses none of the grant's attempts.
+ * Receipts made before `typed` was recorded count when their outcome says the text was delivered.
  */
 export function steerAttempts(records, grantId) {
     return records.filter((r) => {
@@ -145,6 +159,8 @@ export function steerAttempts(records, grantId) {
         const receipt = r.completion_receipt;
         if (!receipt)
             return false;
+        if (receipt.forwarded === true)
+            return true;
         if (typeof receipt.typed === "boolean")
             return receipt.typed;
         const outcome = String(receipt.steer_status ?? receipt.outcome ?? "");
@@ -179,6 +195,15 @@ export function readSteerArtifact(stateDir, recordId) {
     }
 }
 const CAPTURE_LINES = 40;
+const str = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+const fileSize = (path) => {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+};
 /**
  * Run one steer under its grant. The record is the session_steer_request; the
  * grant record is the approved run the steer belongs to. A returned status
@@ -195,6 +220,9 @@ export async function steerSession(deps, args) {
     const grantSession = String(grantRecord.body.session ?? "") || undefined;
     const session = body.session ?? args.binding?.session ?? grantSession;
     let typed = false;
+    let forwarded = false;
+    let route;
+    let transcript = {};
     const finish = (status, message, extra = {}, target) => {
         const artifact = persistArtifact(deps.stateDir, record.id, {
             record: record.id,
@@ -204,14 +232,33 @@ export async function steerSession(deps, args) {
             status,
             message,
             typed,
+            ...(forwarded ? { forwarded } : {}),
+            ...(route ? { route } : {}),
+            ...transcript,
+            ...(target ? { target } : {}),
             ...(args.binding ? { binding: args.binding } : {}),
             at: now().toISOString(),
             ...extra,
         });
-        return { status, message, typed, ...(target ? { target } : {}), artifact };
+        return { status, message, typed, ...(forwarded ? { forwarded } : {}), ...(route ? { route } : {}), ...transcript, ...(target ? { target } : {}), artifact };
     };
     if (!instruction.trim())
         return { status: "blocked", message: "The steer carries no instruction.", typed: false };
+    // Sent before, or about to be when the connector stopped: this answers from that, and nothing is sent again.
+    const sent = readSteerArtifact(deps.stateDir, record.id);
+    if (sent?.typed === true || sent?.forwarded === true) {
+        const earlierRoute = sent.route;
+        return {
+            status: sent.status,
+            message: String(sent.message ?? ""),
+            typed: sent.typed === true,
+            ...(sent.forwarded === true ? { forwarded: true } : {}),
+            ...(earlierRoute ? { route: earlierRoute } : {}),
+            ...(typeof sent.transcript_offset === "number" ? { transcript_offset: sent.transcript_offset } : {}),
+            ...(typeof sent.target === "string" ? { target: sent.target } : {}),
+            artifact: { file: artifactPath(deps.stateDir, record.id), sha256: String(sent.instruction_sha256 ?? "") },
+        };
+    }
     if (!session)
         return finish("stale_binding", "Neither the steer nor its grant names a session; a steer never targets whichever pane is active.");
     if (body.session && grantSession && body.session !== grantSession) {
@@ -263,6 +310,48 @@ export async function steerSession(deps, args) {
     if (!agentCommands.includes(pane.command)) {
         return finish("wrong_pane", `Pane ${target} runs "${pane.command}", not an agent; nothing was typed.`, { pane: { ...pane } }, target);
     }
+    if (args.sameInstructionSent && !args.authorized) {
+        return finish("duplicate", `These same words were already sent under this grant as ${args.sameInstructionSent}; they are not sent twice. Reword it if you mean something new.`, { earlier: args.sameInstructionSent }, target);
+    }
+    // A mission bound to a session is answered about that session: the mission's own binding, Claude
+    // Code's registry and the adapter's file, never a reading of the pane (jgwill/Miadi#930).
+    const provider = args.binding?.provider ?? str(grantRecord.body.resolved_provider) ?? str(grantRecord.body.provider);
+    const runtime = deps.runtime
+        ? resolveRuntime(deps.runtime, { session_id: args.binding?.session_id, pane_id: pane.id, provider })
+        : { route: "none", code: "unsupported", reason: "This host has no runtime steering route configured." };
+    if (runtime.route === "none" && runtime.code !== "unsupported") {
+        return finish(runtime.code, `${runtime.reason} Nothing was sent.`, { pane: { ...pane } }, target);
+    }
+    // The runtime owns when its model reads this. The connector hands it over and is done.
+    const forward = (rt) => {
+        const earlier = sameInstructionInFlight(deps.runtime, rt.session_id, grantRecord.id, instruction);
+        if (earlier && earlier !== record.id) {
+            return finish("duplicate", `These same words were already forwarded to this session as ${earlier}; they are not sent twice.`, { earlier }, target);
+        }
+        try {
+            const actor = record.actor;
+            const { file, already, envelope } = enqueueSteer(deps.runtime, {
+                steer: record.id,
+                grant: grantRecord.id,
+                session_id: rt.session_id,
+                instruction,
+                from: { person_id: actor.person_id, name: actor.name, ...(actor.client_name ? { via: actor.client_name } : {}) },
+                // A person's decision on this exact steer stands apart from the grant it cites: the grant's expiry and revocation do not stop it.
+                ...(args.authorized ? { decided: true } : grant?.expires_at ? { grant_expires_at: grant.expires_at } : {}),
+                ...(rt.transcript_path ? { transcript_path: rt.transcript_path } : {}),
+                now: now(),
+            });
+            forwarded = true;
+            route = "claude_hook_inbox";
+            transcript = envelope.transcript_offset !== undefined ? { transcript_offset: envelope.transcript_offset } : {};
+            return finish("queued_at_runtime", `Handed to the inbox of Claude Code session ${rt.session_id}. Its own hooks present it to its model at its next continuation, in the same turn. This is not yet proof the model read it.`, { inbox_file: file, already_queued: already, queued_at: envelope.queued_at, expires_at: envelope.expires_at }, target);
+        }
+        catch (error) {
+            return finish("blocked", `The inbox of session ${rt.session_id} refused the steer (${error instanceof Error ? error.message : String(error)}); nothing was forwarded.`, {}, target);
+        }
+    };
+    if (runtime.route === "claude_hook_inbox" && runtime.seat !== "idle")
+        return forward(runtime);
     let before;
     try {
         before = deps.tmux.capture(target);
@@ -271,22 +360,38 @@ export async function steerSession(deps, args) {
         return finish("blocked", `The pane could not be read (${error instanceof Error ? error.message : String(error)}); nothing was typed.`, {}, target);
     }
     if (isBusy(before)) {
-        return finish("busy", `The agent in ${target} is mid-turn; the steer was not typed. Ask again when it is idle.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
+        if (runtime.route === "claude_hook_inbox")
+            return forward(runtime);
+        return finish("unsupported", `The agent in ${target} is working and has no runtime steering route: ${runtime.route === "none" ? runtime.reason : ""} Nothing was typed.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
     }
     const composing = composingText(before);
     if (composing === null) {
+        if (runtime.route === "claude_hook_inbox")
+            return forward(runtime);
         return finish("blocked", `The prompt box of ${target} (${pane.command}) cannot be read, so whether someone is writing there cannot be told. Nothing was typed.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
     }
     if (composing) {
+        // Someone's words are at the prompt: the inbox waits for their prompt and never touches them.
+        if (runtime.route === "claude_hook_inbox")
+            return forward(runtime);
         return finish("composing", `Text already sits at the prompt in ${target}; someone may be writing. Nothing was typed and Enter was not pressed.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
     }
+    if (deps.runtime && args.binding?.session_id) {
+        const path = transcriptPathOf(deps.runtime, args.binding.session_id);
+        if (path)
+            transcript = { transcript_offset: fileSize(path) };
+    }
+    // Written before the keys: a connector stopped between here and the receipt never types it twice.
+    persistArtifact(deps.stateDir, record.id, { record: record.id, grant: grantRecord.id, instruction, session, status: "submitted", message: `Typed into ${target}; the connector stopped before it could say more.`, typed: true, route: "tmux_exact_pane", ...transcript, target, at: now().toISOString() });
     try {
         deps.tmux.sendLiteral(target, instruction);
     }
     catch (error) {
+        // finish() overwrites the artifact written above: nothing was typed, so a later call may try again.
         return finish("blocked", `tmux refused the text for ${target} (${error instanceof Error ? error.message : String(error)}); nothing was typed.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
     }
     typed = true;
+    route = "tmux_exact_pane";
     try {
         deps.tmux.sendEnter(target);
     }

package/dist/store.d.ts

@@ -17,6 +17,8 @@ export declare class Ledger<R extends {
     private cache;
     constructor(path: string);
     append(record: R): R;
+    /** A processing receipt is committed to disk before its dependent stage starts. */
+    appendDurable(record: R): R;
     all(): R[];
 }
 export declare function statePaths(dir: string): {

package/dist/store.js

@@ -10,7 +10,7 @@
  *                (observations, handoffs, proposals). Append-only: a record
  *                is never edited, a later record supersedes it.
  */
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, statSync, writeSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { readJsonSafe, writeJsonAtomic } from "@miadi/node-service-kit/json";
@@ -66,6 +66,23 @@ export class Ledger {
         appendFileSync(this.path, JSON.stringify(record) + "\n", { mode: 0o600 });
         return record;
     }
+    /** A processing receipt is committed to disk before its dependent stage starts. */
+    appendDurable(record) {
+        const fd = openSync(this.path, "a", 0o600);
+        try {
+            // Keep a torn crash tail separate from this record, as all() skips invalid lines.
+            const old = readFileSync(this.path);
+            const line = Buffer.from((old.length && old[old.length - 1] !== 10 ? "\n" : "") + JSON.stringify(record) + "\n");
+            let written = 0;
+            while (written < line.length)
+                written += writeSync(fd, line, written, line.length - written);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return record;
+    }
     all() {
         if (!existsSync(this.path))
             return [];

package/dist/tools.d.ts

@@ -9,6 +9,7 @@ import { type ApprovalDeps } from "./approve.js";
 import { type DecisionTokens } from "./decisions.js";
 import { type DiscoveryProbe, type ProviderId } from "./providers.js";
 import { type JevAdapter } from "./model-preflight.js";
+import { type RuntimeDeps } from "./runtime-steer.js";
 import { type TmuxLike } from "./steer.js";
 import { type GithubGet } from "./mission-result.js";
 export interface ToolContext {
@@ -24,6 +25,8 @@ export interface ToolContext {
     decisionTokens?: DecisionTokens;
     /** The steering surface (jgwill/Miadi#893); absent, steering answers unavailable. */
     tmux?: TmuxLike;
+    /** Where sessions and their steering inboxes live (jgwill/Miadi#930). Absent, no runtime route is known. */
+    steeringRuntime?: RuntimeDeps;
     tmuxSessions?: () => string[];
     /** Provider discovery probes; tests inject fakes (jgwill/Miadi#893). */
     providersProbe?: DiscoveryProbe;
@@ -42,7 +45,32 @@ export interface ToolContext {
 export declare function githubAccess(status: number, hasToken: boolean): string;
 /** A GitHub REST read as the connector can make it: GITHUB_TOKEN when the host has one, else anonymous. */
 export declare function githubGetter(fetchImpl?: typeof fetch, token?: string | undefined): GithubGet;
-/** Whether the steering transport works now: registered is not operational (jgwill/Miadi#909). */
+export declare const STEERING_CONTRACT: {
+    readonly busy_is_normal: true;
+    readonly connector: "Admits the steer, resolves mission → session → runtime, hands it to that session's inbox and reports what the runtime accepted. It does not watch tools or wait for idle.";
+    readonly runtime: "The agent's own lifecycle presents it to its model at the next supported continuation in the same turn.";
+    readonly delivery_states: readonly ["authorized", "forwarded_to_runtime", "queued_at_runtime", "delivered_to_agent_context", "acknowledged", "behavior_adjusted", "unsupported", "expired", "blocked", "unknown"];
+    readonly provider_adapters: {
+        readonly claude: {
+            readonly route: "claude_hook_inbox";
+            readonly continuation: "PostToolUse, PostToolUseFailure, then Stop if no tool follows";
+            readonly needs: "miadi-session-observability 0.1.34 or later, loaded when the session started";
+        };
+        readonly codex: {
+            readonly route: "unsupported";
+        };
+        readonly copilot: {
+            readonly route: "unsupported";
+        };
+        readonly pi: {
+            readonly route: "unsupported";
+        };
+        readonly gemini: {
+            readonly route: "unsupported";
+        };
+    };
+    readonly idle_seat: "An idle seat has no continuation coming, so its steer is typed into its bound pane once the prompt reads empty.";
+};
 export declare function steeringTransport(tmux: TmuxLike | undefined): {
     tool: "registered";
     transport: "operational" | "unavailable";