@miadi/connector 0.1.8 → 0.1.10

package/dist/server.d.ts

@@ -3,12 +3,20 @@ import type { MiadiPerson } from "./people.js";
 import { Ledger } from "./store.js";
 import type { ConnectorRecord } from "./records.js";
 import type { ConnectorConfig } from "./config.js";
+import type { TmuxLike } from "./steer.js";
+import type { DiscoveryProbe } from "./providers.js";
 export interface ConnectorDeps {
     identify: (token: string) => Promise<MiadiPerson | null>;
     fetchImpl?: typeof fetch;
     /** The factory directory holding queue/ (default ~/.miadi/factory). */
     factoryDir?: string;
     tmuxSessions?: () => string[];
+    /** The steering surface (jgwill/Miadi#893); tests inject a fake, production uses tmux. */
+    tmux?: TmuxLike;
+    /** Provider discovery probes (jgwill/Miadi#893); tests inject fakes. */
+    providersProbe?: DiscoveryProbe;
+    /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
+    steerSettleMs?: number;
     /** Person-token attempts allowed per address in 15 minutes on each sign-in form (default 30). */
     tokenAttemptsPerWindow?: number;
 }

package/dist/server.js

@@ -85,6 +85,8 @@ export function createConnectorApp(config, deps) {
         fetchImpl: deps.fetchImpl,
         factoryDir: deps.factoryDir,
         tmuxSessions: deps.tmuxSessions,
+        tmux: deps.tmux,
+        steerSettleMs: deps.steerSettleMs,
     };
     registerApprovalRoutes(app, approvalDeps);
     const decisionTokens = new DecisionTokens(config.stateDir);
@@ -94,7 +96,20 @@ export function createConnectorApp(config, deps) {
         resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl),
     });
     const handle = async (req, res) => {
-        const ctx = { config, miadi, reviews, ledger, oauthState, factoryDir: deps.factoryDir, approval: approvalDeps, decisionTokens };
+        const ctx = {
+            config,
+            miadi,
+            reviews,
+            ledger,
+            oauthState,
+            factoryDir: deps.factoryDir,
+            approval: approvalDeps,
+            decisionTokens,
+            tmux: deps.tmux,
+            tmuxSessions: deps.tmuxSessions,
+            providersProbe: deps.providersProbe,
+            steerSettleMs: deps.steerSettleMs,
+        };
         const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
         registerTools(server, ctx);
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });

package/dist/steer.d.ts

@@ -0,0 +1,71 @@
+import { execFileSync } from "node:child_process";
+import type { ConnectorRecord } from "./records.js";
+export declare const STEER_STATUSES: readonly ["prepared", "submitted", "accepted", "busy", "blocked", "wrong_pane", "stale_binding", "expired_grant", "duplicate"];
+export type SteerStatus = (typeof STEER_STATUSES)[number];
+/** The steering grant an approved run carries: `body.steering` on the run_request or work proposal. */
+export interface SteeringGrant {
+    /** How many steers the approval covers. */
+    max_attempts?: number;
+    /** ISO time after which no steer runs under this grant. */
+    expires_at?: string;
+    /** The pane the seat lives in, `window.pane` (default the session's first pane). */
+    pane?: string;
+}
+export interface PaneInfo {
+    /** tmux pane id, e.g. %67 — evidence only, never the address. */
+    id: string;
+    window: number;
+    pane: number;
+    command: string;
+    active: boolean;
+}
+/** The tmux surface the steer needs, injectable so tests never touch a live pane. */
+export interface TmuxLike {
+    listPanes(session: string): PaneInfo[];
+    capture(target: string): string;
+    sendLiteral(target: string, text: string): void;
+    sendEnter(target: string): void;
+}
+/** Commands that mark a pane as an agent seat a steer may land in. */
+export declare const AGENT_COMMANDS: string[];
+/** Signs a seat is mid-turn; typed text would queue behind its work. */
+export declare const BUSY_PATTERNS: RegExp[];
+/** The production adapter. All tmux addressing is by exact session and window.pane. */
+export declare function tmuxAdapter(exec?: typeof execFileSync): TmuxLike;
+export declare function steeringGrantOf(run: ConnectorRecord): SteeringGrant | null;
+export type GrantCheck = "ok" | "no_grant" | "expired_grant" | "duplicate";
+/** Whether a grant covers one more steer. `priorAttempts` counts the steers already run under it. */
+export declare function checkGrant(grant: SteeringGrant | null, priorAttempts: number, now?: Date): GrantCheck;
+/** Steers already run under a grant: decided (or grant-covered) steer records that cite it. */
+export declare function steerAttempts(records: ConnectorRecord[], grantId: string): number;
+export declare function isBusy(capture: string, patterns?: RegExp[]): boolean;
+export interface SteerDeps {
+    tmux: TmuxLike;
+    stateDir: string;
+    now?: () => Date;
+    settleMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    agentCommands?: string[];
+}
+export interface SteerResult {
+    status: SteerStatus;
+    message: string;
+    target?: string;
+    artifact?: {
+        file: string;
+        sha256: string;
+    };
+}
+/** The artifact as last written, when a caller asks again with the same idempotency key. */
+export declare function readSteerArtifact(stateDir: string, recordId: string): Record<string, unknown> | null;
+/**
+ * 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
+ * other than `accepted`/`submitted` means nothing was typed.
+ */
+export declare function steerSession(deps: SteerDeps, args: {
+    record: ConnectorRecord;
+    grantRecord: ConnectorRecord;
+    priorAttempts: number;
+    authorized?: boolean;
+}): Promise<SteerResult>;

package/dist/steer.js

@@ -0,0 +1,229 @@
+/**
+ * Approval-aware session steering (jgwill/Miadi#893, Phase 1B): one authorized
+ * follow-up to one existing live agent, never raw tmux handed to a model.
+ *
+ * The rules this file keeps:
+ * - 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.
+ * - 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
+ *   parsed as a directive.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const STEER_STATUSES = [
+    "prepared",
+    "submitted",
+    "accepted",
+    "busy",
+    "blocked",
+    "wrong_pane",
+    "stale_binding",
+    "expired_grant",
+    "duplicate",
+];
+/** Commands that mark a pane as an agent seat a steer may land in. */
+export const AGENT_COMMANDS = ["claude", "codex", "copilot", "pi", "gemini", "node"];
+/** Signs a seat is mid-turn; typed text would queue behind its work. */
+export const BUSY_PATTERNS = [/esc (to )?interrupt/i, /[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]/, /\bWorking\b/, /\bThinking\b/];
+/** The production adapter. All tmux addressing is by exact session and window.pane. */
+export function tmuxAdapter(exec = execFileSync) {
+    const tmux = (args) => exec("tmux", args, { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
+    return {
+        listPanes(session) {
+            const out = tmux(["list-panes", "-s", "-t", session, "-F", "#{pane_id}\t#{window_index}\t#{pane_index}\t#{pane_current_command}\t#{pane_active}"]);
+            return out
+                .split("\n")
+                .filter(Boolean)
+                .map((line) => {
+                const [id, w, p, command, active] = line.split("\t");
+                return { id, window: Number(w), pane: Number(p), command, active: active === "1" };
+            })
+                .sort((a, b) => a.window - b.window || a.pane - b.pane);
+        },
+        capture(target) {
+            return tmux(["capture-pane", "-p", "-t", target]);
+        },
+        // -l: the text is literal; no tmux key names in an instruction are interpreted.
+        sendLiteral(target, text) {
+            tmux(["send-keys", "-t", target, "-l", "--", text]);
+        },
+        sendEnter(target) {
+            tmux(["send-keys", "-t", target, "Enter"]);
+        },
+    };
+}
+export function steeringGrantOf(run) {
+    const g = run.body.steering;
+    if (!g || typeof g !== "object")
+        return null;
+    const grant = g;
+    return {
+        ...(typeof grant.max_attempts === "number" ? { max_attempts: grant.max_attempts } : {}),
+        ...(typeof grant.expires_at === "string" ? { expires_at: grant.expires_at } : {}),
+        ...(typeof grant.pane === "string" ? { pane: grant.pane } : {}),
+    };
+}
+/** Whether a grant covers one more steer. `priorAttempts` counts the steers already run under it. */
+export function checkGrant(grant, priorAttempts, now = new Date()) {
+    if (!grant)
+        return "no_grant";
+    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";
+}
+/** Steers already run under a grant: decided (or grant-covered) steer records that cite it. */
+export function steerAttempts(records, grantId) {
+    return records.filter((r) => r.kind === "session_steer_request" &&
+        r.refs.includes(grantId) &&
+        (r.approval_state === "approved" || r.approval_state === "not_required") &&
+        r.completion_receipt !== undefined).length;
+}
+const targetName = (session, pane) => `${session}:${pane.window}.${pane.pane}`;
+export function isBusy(capture, patterns = BUSY_PATTERNS) {
+    const tail = capture.split("\n").slice(-25).join("\n");
+    return patterns.some((p) => p.test(tail));
+}
+function artifactPath(stateDir, recordId) {
+    return join(stateDir, "steers", `${recordId.replace(/[^\w-]/g, "-")}.json`);
+}
+function persistArtifact(stateDir, recordId, artifact) {
+    const file = artifactPath(stateDir, recordId);
+    mkdirSync(join(stateDir, "steers"), { recursive: true, mode: 0o700 });
+    const sha256 = createHash("sha256").update(JSON.stringify(artifact.instruction)).digest("hex");
+    writeFileSync(file, JSON.stringify({ ...artifact, instruction_sha256: sha256 }, null, 2) + "\n", { mode: 0o600 });
+    return { file, sha256 };
+}
+/** The artifact as last written, when a caller asks again with the same idempotency key. */
+export function readSteerArtifact(stateDir, recordId) {
+    const file = artifactPath(stateDir, recordId);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const CAPTURE_LINES = 40;
+/**
+ * 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
+ * other than `accepted`/`submitted` means nothing was typed.
+ */
+export async function steerSession(deps, args) {
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const agentCommands = deps.agentCommands ?? AGENT_COMMANDS;
+    const { record, grantRecord } = args;
+    const body = record.body;
+    const grant = steeringGrantOf(grantRecord);
+    const instruction = String(body.instruction ?? "");
+    const grantSession = String(grantRecord.body.session ?? "") || undefined;
+    const session = body.session ?? grantSession;
+    const finish = (status, message, extra = {}, target) => {
+        const artifact = persistArtifact(deps.stateDir, record.id, {
+            record: record.id,
+            grant: grantRecord.id,
+            instruction,
+            session,
+            status,
+            message,
+            at: now().toISOString(),
+            ...extra,
+        });
+        return { status, message, ...(target ? { target } : {}), artifact };
+    };
+    if (!instruction.trim())
+        return { status: "blocked", message: "The steer carries no instruction." };
+    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) {
+        return finish("stale_binding", `The steer names session "${body.session}" but its grant covers "${grantSession}".`);
+    }
+    // A person's approval of this exact steer covers one attempt even when the
+    // run's grant is exhausted; without it, the grant's own limits decide.
+    if (!args.authorized) {
+        const check = checkGrant(grant, args.priorAttempts, now());
+        if (check === "expired_grant")
+            return finish("expired_grant", `The steering grant expired at ${grant?.expires_at}.`, {}, session);
+        if (check === "duplicate") {
+            return finish("duplicate", `The grant's ${grant?.max_attempts ?? 0} steer(s) are used; a new scoped human decision is needed for more.`, {}, session);
+        }
+    }
+    let panes;
+    try {
+        panes = deps.tmux.listPanes(session);
+    }
+    catch {
+        return finish("stale_binding", `No tmux session named "${session}"; the binding is stale.`, {}, session);
+    }
+    if (!panes.length)
+        return finish("stale_binding", `Session "${session}" has no panes; the binding is stale.`, {}, session);
+    const wanted = body.pane ?? grant?.pane;
+    let pane;
+    if (wanted) {
+        const [w, p] = wanted.split(".").map(Number);
+        pane = panes.find((x) => x.window === w && x.pane === p);
+        if (!pane)
+            return finish("stale_binding", `Pane ${wanted} of "${session}" is gone (stale or renumbered); nothing was typed anywhere else.`, {}, session);
+    }
+    else {
+        pane = panes[0]; // listPanes is sorted: lowest window, lowest pane (jgwill/Miadi#725).
+    }
+    const target = targetName(session, pane);
+    if (!agentCommands.includes(pane.command)) {
+        return finish("wrong_pane", `Pane ${target} runs "${pane.command}", not an agent; nothing was typed.`, { pane: { ...pane } }, target);
+    }
+    let before;
+    try {
+        before = deps.tmux.capture(target);
+    }
+    catch (error) {
+        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);
+    }
+    deps.tmux.sendLiteral(target, instruction);
+    deps.tmux.sendEnter(target);
+    await sleep(deps.settleMs ?? 4000);
+    let after;
+    try {
+        after = deps.tmux.capture(target);
+    }
+    catch (error) {
+        return finish("submitted", `Typed into ${target}, but the re-peek failed (${error instanceof Error ? error.message : String(error)}); acceptance is unconfirmed.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
+    }
+    let current;
+    try {
+        current = deps.tmux.listPanes(session).find((x) => x.window === pane.window && x.pane === pane.pane);
+    }
+    catch {
+        current = undefined;
+    }
+    const tail = after.split("\n").slice(-CAPTURE_LINES);
+    const evidence = { peek: before.split("\n").slice(-CAPTURE_LINES), re_peek: tail };
+    if (!current || current.command !== pane.command) {
+        return finish("stale_binding", `Typed into ${target}, but the pane's command changed while sending; the seat may have exited. Acceptance is unconfirmed.`, evidence, target);
+    }
+    const firstLine = instruction.split("\n")[0].slice(0, 80);
+    const echoed = firstLine.length > 0 && after.includes(firstLine);
+    if (isBusy(after) && echoed) {
+        return finish("accepted", `The agent in ${target} is processing the steer.`, evidence, target);
+    }
+    const stillAtPrompt = tail.some((l) => firstLine.length > 0 && l.includes(firstLine)) && !isBusy(after);
+    return finish("submitted", stillAtPrompt
+        ? `The instruction sits at the prompt in ${target}; it was typed but the agent has not accepted it.`
+        : `Typed into ${target}; the pane shows no processing sign, so acceptance is unconfirmed.`, evidence, target);
+}

package/dist/tools.d.ts

@@ -7,6 +7,8 @@ import type { OAuthState } from "./oauth.js";
 import { type ConnectorRecord } from "./records.js";
 import { type ApprovalDeps } from "./approve.js";
 import { type DecisionTokens } from "./decisions.js";
+import { type DiscoveryProbe } from "./providers.js";
+import { type TmuxLike } from "./steer.js";
 export interface ToolContext {
     config: ConnectorConfig;
     miadi: MiadiClient;
@@ -18,6 +20,13 @@ export interface ToolContext {
     /** What the in-chat approval card needs to run a decided request. */
     approval?: ApprovalDeps;
     decisionTokens?: DecisionTokens;
+    /** The steering surface (jgwill/Miadi#893); absent, steering answers unavailable. */
+    tmux?: TmuxLike;
+    tmuxSessions?: () => string[];
+    /** Provider discovery probes; tests inject fakes (jgwill/Miadi#893). */
+    providersProbe?: DiscoveryProbe;
+    /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
+    steerSettleMs?: number;
 }
 export declare function registerTools(server: McpServer, ctx: ToolContext): void;
 /** What get_capabilities reports for each tool. */