@miadi/connector 0.1.19 → 0.1.21

package/dist/research-shelf.d.ts

@@ -0,0 +1,173 @@
+import { type ArtefactWeave } from "@miadi/inquiry-weave";
+import { type ReportDigest } from "./research-digest.js";
+/** A saved report may be 1 MB of characters; several times that is not a document anyone reads through a tool. */
+export declare const MAX_SHELF_FILE_BYTES: number;
+export declare class ShelfRefusal extends Error {
+    readonly code: "invalid_ref" | "not_found" | "forbidden";
+    constructor(code: "invalid_ref" | "not_found" | "forbidden", message: string);
+}
+/** Who may read a folder. `weave` is undefined for a folder no one saved through a door. */
+export declare function canReadShelf(weave: ArtefactWeave | undefined, person: {
+    id: string;
+    api_tier: string | null;
+}): boolean;
+export interface ShelfReadOptions {
+    file?: string;
+    offset?: number;
+    revision?: string;
+    maxBytes?: number;
+}
+/** The folder's manifest, and one file's page when a file is named or the folder holds its report. */
+export declare function readShelfArtefact(root: string, name: string, person: {
+    id: string;
+    api_tier: string | null;
+}, opts?: ShelfReadOptions): Promise<{
+    note: string;
+    files_truncated?: string | undefined;
+    episodes: string[];
+    git: {
+        commit?: string;
+        committed_at?: string;
+        uncommitted_changes?: boolean;
+        state: "known" | "unknown";
+    };
+    files: {
+        path: string;
+        bytes: number;
+        sha256?: string;
+        readable: boolean;
+    }[];
+    saved?: {
+        file: string;
+        sha256: string;
+        bytes: number;
+        saved_at: string;
+        via: string | undefined;
+        refs: string[];
+    } | undefined;
+    issue?: string | undefined;
+    issue_url?: string | undefined;
+    circle?: string | undefined;
+    visibility: "circle" | "published" | "private" | "proposed";
+    owner?: {
+        person_id: string;
+        name: string | undefined;
+    } | undefined;
+    artefact: string;
+} | {
+    page: {
+        offset: number;
+        end: number;
+        bytes: number;
+        sha256: string;
+        complete: boolean;
+        next: {
+            offset: number;
+            revision: string;
+        } | null;
+    };
+    text: string;
+    modified_at?: string | undefined;
+    verification?: string | undefined;
+    bytes: number;
+    sha256: string;
+    verified: boolean;
+    file: string;
+    content_type: string;
+    integrity: string;
+    file_git: {
+        commit?: string;
+        committed_at?: string;
+        uncommitted_changes?: boolean;
+        state: "known" | "unknown";
+    };
+    files_truncated?: string | undefined;
+    episodes: string[];
+    git: {
+        commit?: string;
+        committed_at?: string;
+        uncommitted_changes?: boolean;
+        state: "known" | "unknown";
+    };
+    files: {
+        path: string;
+        bytes: number;
+        sha256?: string;
+        readable: boolean;
+    }[];
+    saved?: {
+        file: string;
+        sha256: string;
+        bytes: number;
+        saved_at: string;
+        via: string | undefined;
+        refs: string[];
+    } | undefined;
+    issue?: string | undefined;
+    issue_url?: string | undefined;
+    circle?: string | undefined;
+    visibility: "circle" | "published" | "private" | "proposed";
+    owner?: {
+        person_id: string;
+        name: string | undefined;
+    } | undefined;
+    artefact: string;
+}>;
+/** One thing on the shelf, as its own files say it is: computed from them, never summarised. */
+export interface ShelfListing extends ReportDigest {
+    ref: string;
+    artefact: string;
+    /** `report`: saved through a door, with its hash. `folder`: anything else with a document. `notes`: agent instructions or unreadable files only. */
+    kind: "report" | "folder" | "notes";
+    /** The document its title and opening come from, the one a reader opens on. */
+    main?: string;
+    files: number;
+    /** Saved, or last woven, or its main document's last change. */
+    at?: string;
+    owner?: {
+        person_id: string;
+        name?: string;
+    };
+    visibility: string;
+    circle?: string;
+    issue?: string;
+    issue_url?: string;
+    episodes: {
+        number?: number;
+        title: string;
+    }[];
+    saved?: {
+        sha256: string;
+        bytes: number;
+        saved_at: string;
+        via?: string;
+        refs: string[];
+    };
+}
+/** One folder's listing. A folder that cannot be read is listed by its name. */
+export declare function shelfListing(root: string, name: string, weave: ArtefactWeave | undefined): ShelfListing;
+export type ShelfSort = "newest" | "oldest" | "longest" | "title";
+export declare function sortListings(items: ShelfListing[], sort?: ShelfSort): ShelfListing[];
+/**
+ * The shelf as this person may read it. `mine` is what they own. `all` is every folder, the write
+ * tier's alone, because a folder another person owns or no one owns is theirs to read and no one else's.
+ */
+export declare function listShelfArtefacts(root: string, person: {
+    id: string;
+    api_tier: string | null;
+}, opts?: {
+    scope?: "mine" | "all";
+    query?: string;
+    kind?: ShelfListing["kind"];
+    sort?: ShelfSort;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    scope: "mine" | "all";
+    total: number;
+    offset: number;
+    limit: number;
+    items: ShelfListing[];
+    next_offset: number | null;
+    read_with: string;
+}>;

package/dist/research-shelf.js

@@ -0,0 +1,297 @@
+/**
+ * Reading what is on the inquiry shelf (jgwill/Miadi#879). save_research and the agents who work
+ * on the shelf write here, and this reads it back from a later conversation without another mission.
+ *
+ * Who may read: the folder's owner, or Miadi's write tier. That is the same rule the shelf's other
+ * doors keep, and a folder with no owner recorded is the write tier's alone. No one has defined who
+ * sits in a circle for `visibility: circle`, so sharing with a circle admits no one new until that
+ * is decided.
+ *
+ * What can be read: the text files the episode doors read, by their path in the folder. Hidden
+ * paths, links, and anything outside the folder are never served. Each answer says whether the
+ * bytes are still the bytes saved and which commit holds them.
+ */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { promisify } from "node:util";
+import { artefactVisibility, readArtefactWeave } from "@miadi/inquiry-weave";
+import { FileRefusal, checkRelativePath, extensionOf, pageOf, TEXT_TYPES } from "./episode-files.js";
+import { digestReport, folderTitle } from "./research-digest.js";
+const run = promisify(execFile);
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const REPORT_FILE = "report.md";
+/** A saved report may be 1 MB of characters; several times that is not a document anyone reads through a tool. */
+export const MAX_SHELF_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_LISTED_FILES = 200;
+export class ShelfRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Who may read a folder. `weave` is undefined for a folder no one saved through a door. */
+export function canReadShelf(weave, person) {
+    if (person.api_tier === "write")
+        return true;
+    if (!weave)
+        return false;
+    return weave.owner?.person_id === person.id;
+}
+function folderOf(root, name) {
+    if (!/^[\w.-]+$/.test(name) || name.startsWith("."))
+        throw new ShelfRefusal("invalid_ref", "Give the shelf folder's name, inquiry-artefact:<name> or the research_artifact record id.");
+    const dir = join(root, name);
+    let st;
+    try {
+        st = lstatSync(dir);
+    }
+    catch {
+        throw new ShelfRefusal("not_found", `No folder ${name} on the inquiry shelf.`);
+    }
+    if (!st.isDirectory())
+        throw new ShelfRefusal("not_found", `No folder ${name} on the inquiry shelf.`);
+    return dir;
+}
+function listFiles(dir) {
+    const files = [];
+    let truncated = false;
+    const walk = (at) => {
+        for (const entry of readdirSync(at, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith(".") || entry.isSymbolicLink())
+                continue;
+            const full = join(at, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (files.length >= MAX_LISTED_FILES) {
+                truncated = true;
+                return;
+            }
+            const path = relative(dir, full).split(sep).join("/");
+            const bytes = lstatSync(full).size;
+            const readable = extensionOf(path) in TEXT_TYPES && bytes <= MAX_SHELF_FILE_BYTES;
+            files.push({ path, bytes, readable, ...(readable ? { sha256: sha256(readFileSync(full)) } : {}) });
+        }
+    };
+    walk(dir);
+    return { files, truncated };
+}
+/** The bytes of one file in the folder, refusing anything that leaves it. */
+function readInside(dir, file) {
+    let segments;
+    try {
+        segments = checkRelativePath(file);
+    }
+    catch {
+        throw new FileRefusal("invalid_path", "Name a file by its path in the folder, as files lists it. Hidden, absolute and '..' paths are not read.");
+    }
+    if (!(extensionOf(file) in TEXT_TYPES))
+        throw new FileRefusal("unsupported", `Only text files are read here (${Object.keys(TEXT_TYPES).join(", ")}).`);
+    let walked = dir;
+    for (const segment of segments) {
+        walked = join(walked, segment);
+        let st;
+        try {
+            st = lstatSync(walked);
+        }
+        catch {
+            throw new ShelfRefusal("not_found", `No file ${file} in that folder.`);
+        }
+        if (st.isSymbolicLink())
+            throw new FileRefusal("invalid_path", `${file} passes through a link; shelf files are read by their own path only.`);
+    }
+    const final = lstatSync(walked);
+    if (!final.isFile())
+        throw new ShelfRefusal("not_found", `No file ${file} in that folder.`);
+    if (final.size > MAX_SHELF_FILE_BYTES)
+        throw new FileRefusal("unsupported", `${file} is ${final.size} bytes, more than the ${MAX_SHELF_FILE_BYTES} this door reads.`);
+    if (!realpathSync(walked).startsWith(realpathSync(dir) + sep))
+        throw new FileRefusal("invalid_path", `${file} is outside its folder.`);
+    return readFileSync(walked);
+}
+/** Which commit last held the folder, and whether what is on disk differs from it. Unknown when git cannot say, never guessed. */
+async function gitStateOf(dir, path = ".") {
+    try {
+        const log = (await run("git", ["-C", dir, "log", "-1", "--format=%H%n%cI", "--", path], { timeout: 5000 })).stdout.trim().split("\n");
+        const status = (await run("git", ["-C", dir, "status", "--porcelain", "--", path], { timeout: 5000 })).stdout;
+        return { state: "known", ...(log[0] ? { commit: log[0], committed_at: log[1] } : {}), uncommitted_changes: status.trim().length > 0 };
+    }
+    catch {
+        return { state: "unknown" };
+    }
+}
+/** What a folder opens on: its saved report, its README, or its one document. Agent instructions are not what a folder is about. */
+function defaultFile(files, saved) {
+    const has = (path) => (path && files.some((f) => f.path === path && f.readable) ? path : undefined);
+    const documents = files.filter((f) => f.readable && !/^(AGENTS|CLAUDE)\.md$/i.test(f.path));
+    return has(saved) ?? has(REPORT_FILE) ?? has("README.md") ?? (documents.length === 1 ? documents[0].path : files.length === 1 && files[0].readable ? files[0].path : undefined);
+}
+/** The folder's manifest, and one file's page when a file is named or the folder holds its report. */
+export async function readShelfArtefact(root, name, person, opts = {}) {
+    const dir = folderOf(root, name);
+    const weave = await readArtefactWeave(dir).catch(() => undefined);
+    if (!canReadShelf(weave, person)) {
+        throw new ShelfRefusal("forbidden", weave ? "That folder belongs to another person. Its owner or a person with Miadi's write tier can read it." : "No owner is recorded for that folder, so only a person with Miadi's write tier can read it.");
+    }
+    const { files, truncated } = listFiles(dir);
+    const manifest = {
+        artefact: name,
+        ...(weave?.owner ? { owner: { person_id: weave.owner.person_id, name: weave.owner.name } } : {}),
+        visibility: artefactVisibility(weave),
+        ...(weave?.circle ? { circle: weave.circle } : {}),
+        ...(weave?.issue ? { issue: weave.issue, issue_url: weave.issue_url } : {}),
+        ...(weave?.source ? { saved: { file: weave.source.file, sha256: weave.source.sha256, bytes: weave.source.bytes, saved_at: weave.source.saved_at, via: weave.source.via, refs: weave.source.refs ?? [] } } : {}),
+        episodes: (weave?.episodes ?? []).map((e) => (e.number !== undefined ? `miadi-chronicle://${e.number}` : e.path)),
+        git: await gitStateOf(dir),
+        files,
+        ...(truncated ? { files_truncated: `Only the first ${MAX_LISTED_FILES} files are listed.` } : {}),
+    };
+    const wanted = opts.file ?? defaultFile(files, weave?.source?.file);
+    if (!wanted)
+        return { ...manifest, note: "Name a file from files to read it." };
+    const bytes = readInside(dir, wanted);
+    let content;
+    try {
+        content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new FileRefusal("unsupported", `${wanted} is not valid UTF-8 text.`);
+    }
+    const whole = sha256(bytes);
+    const page = pageOf({ episode: name, file: wanted, content, size: bytes.byteLength, revision: { sha256: whole, bytes: bytes.byteLength } }, opts);
+    const savedHash = weave?.source?.file === wanted ? weave.source.sha256 : undefined;
+    return {
+        ...manifest,
+        file: wanted,
+        content_type: TEXT_TYPES[extensionOf(wanted)],
+        integrity: savedHash ? (savedHash === whole ? "matches_saved_sha256" : "differs_from_saved_sha256") : "no_saved_sha256",
+        // git above is the whole folder; this is the one file read.
+        file_git: await gitStateOf(dir, wanted),
+        ...page,
+    };
+}
+const MAIN_DOCUMENTS = ["report.md", "README.md", "readme.md"];
+const AGENT_NOTES = /^(AGENTS|CLAUDE)\.md$/i;
+/** One folder's listing. A folder that cannot be read is listed by its name. */
+export function shelfListing(root, name, weave) {
+    const dir = join(root, name);
+    let files = 0;
+    const documents = [];
+    const walk = (at, depth) => {
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            if (entry.name.startsWith(".") || entry.isSymbolicLink())
+                continue;
+            const full = join(at, entry.name);
+            if (entry.isDirectory()) {
+                if (depth < 3)
+                    walk(full, depth + 1);
+            }
+            else if (entry.isFile()) {
+                files++;
+                if (depth === 0 && /\.md$/i.test(entry.name) && !AGENT_NOTES.test(entry.name)) {
+                    const st = statSync(full);
+                    documents.push({ path: entry.name, size: st.size, mtime: st.mtimeMs });
+                }
+            }
+        }
+    };
+    try {
+        walk(dir, 0);
+    }
+    catch {
+        // Listed by its name.
+    }
+    const saved = weave?.source;
+    const main = (saved ? documents.find((d) => d.path === saved.file) : undefined) ??
+        MAIN_DOCUMENTS.map((n) => documents.find((d) => d.path === n)).find(Boolean) ??
+        [...documents].sort((a, b) => b.size - a.size)[0];
+    let digest = { title: folderTitle(name), titled: false, words: 0, minutes: 0, headings: [], sections: 0, sources: 0 };
+    let words = 0;
+    for (const d of documents) {
+        if (d.size > MAX_SHELF_FILE_BYTES)
+            continue;
+        try {
+            const read = digestReport(readFileSync(join(dir, d.path), "utf8"), name);
+            words += read.words;
+            if (d === main)
+                digest = read;
+        }
+        catch {
+            // Listed by its name.
+        }
+    }
+    const woven = (weave?.episodes ?? []).map((e) => e.related_at).filter(Boolean).sort().at(-1);
+    const at = saved?.saved_at ?? woven ?? (main ? new Date(main.mtime).toISOString() : undefined);
+    return {
+        ...digest,
+        words,
+        minutes: Math.max(words ? 1 : 0, Math.round(words / 230)),
+        ref: `inquiry-artefact:${name}`,
+        artefact: name,
+        kind: saved ? "report" : main ? "folder" : "notes",
+        ...(main ? { main: main.path } : {}),
+        files,
+        ...(at ? { at } : {}),
+        ...(weave?.owner ? { owner: { person_id: weave.owner.person_id, name: weave.owner.name } } : {}),
+        visibility: artefactVisibility(weave),
+        ...(weave?.circle ? { circle: weave.circle } : {}),
+        ...(weave?.issue ? { issue: weave.issue } : {}),
+        ...(weave?.issue_url ? { issue_url: weave.issue_url } : {}),
+        episodes: (weave?.episodes ?? []).map((e) => ({
+            ...(e.number !== undefined ? { number: e.number } : {}),
+            title: folderTitle(String(e.path ?? "").split("/").filter(Boolean).at(-1)?.replace(/^\d{4}-\d{2}-\d{2}-episode-\d+-/, "") ?? ""),
+        })),
+        ...(saved ? { saved: { sha256: saved.sha256, bytes: saved.bytes, saved_at: saved.saved_at, ...(saved.via ? { via: saved.via } : {}), refs: saved.refs ?? [] } } : {}),
+    };
+}
+export function sortListings(items, sort = "newest") {
+    const by = {
+        newest: (a, b) => (b.at ?? "").localeCompare(a.at ?? ""),
+        oldest: (a, b) => (a.at ?? "").localeCompare(b.at ?? ""),
+        longest: (a, b) => b.words - a.words,
+        title: (a, b) => a.title.localeCompare(b.title),
+    };
+    return [...items].sort(by[sort]);
+}
+/**
+ * The shelf as this person may read it. `mine` is what they own. `all` is every folder, the write
+ * tier's alone, because a folder another person owns or no one owns is theirs to read and no one else's.
+ */
+export async function listShelfArtefacts(root, person, opts = {}) {
+    const scope = opts.scope ?? "mine";
+    if (scope === "all" && person.api_tier !== "write")
+        throw new ShelfRefusal("forbidden", "Listing the whole shelf needs Miadi's write tier. scope mine lists what you own.");
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 200);
+    const offset = Math.max(opts.offset ?? 0, 0);
+    const q = opts.query?.trim().toLowerCase();
+    const items = [];
+    for (const entry of existsSync(root) ? readdirSync(root, { withFileTypes: true }) : []) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const weave = await readArtefactWeave(join(root, entry.name)).catch(() => undefined);
+        if (scope === "mine" ? weave?.owner?.person_id !== person.id : !canReadShelf(weave, person))
+            continue;
+        const item = shelfListing(root, entry.name, weave);
+        if (opts.kind && item.kind !== opts.kind)
+            continue;
+        if (q && ![item.title, item.excerpt, item.artefact, ...item.headings].some((t) => t?.toLowerCase().includes(q)))
+            continue;
+        items.push(item);
+    }
+    const sorted = sortListings(items, opts.sort ?? "newest");
+    return {
+        scope,
+        total: sorted.length,
+        offset,
+        limit,
+        items: sorted.slice(offset, offset + limit),
+        next_offset: offset + limit < sorted.length ? offset + limit : null,
+        read_with: "read_research_artifact takes an item's artefact, and its main file opens first",
+    };
+}

package/dist/runtime-steer.d.ts

@@ -0,0 +1,182 @@
+export declare const STEER_PROTOCOL = 1;
+/** A correction no continuation consumed in a day is stale: the work has moved on. A grant's own expiry comes sooner when it has one. */
+export declare const ENVELOPE_TTL_MS: number;
+export declare const CLAUDE_ADAPTER = "miadi-session-observability 0.1.34 or later";
+export declare const DELIVERY_STATES: readonly ["authorized", "forwarded_to_runtime", "queued_at_runtime", "delivered_to_agent_context", "acknowledged", "behavior_adjusted", "unsupported", "expired", "blocked", "unknown"];
+export type DeliveryState = (typeof DELIVERY_STATES)[number];
+export interface RuntimeDeps {
+    root: string;
+    claudeDir: string;
+    isAlive?: (pid: number) => boolean;
+}
+export declare function steeringRoot(env?: NodeJS.ProcessEnv): string;
+export declare function defaultRuntime(env?: NodeJS.ProcessEnv): RuntimeDeps;
+/** The token the agent names back in its own text: the same rule as the adapter's ackToken. */
+export declare const ackToken: (steerId: string) => string;
+export interface ClaudeSessionRecord {
+    pid: number;
+    sessionId: string;
+    status?: string;
+    tmux?: string;
+    version?: string;
+}
+/** Claude Code's own record of a running session, `<claudeDir>/sessions/<pid>.json`, if its process lives. */
+export declare function readClaudeSession(deps: RuntimeDeps, sessionId: string): ClaudeSessionRecord | null;
+export type RuntimeRoute = {
+    route: "claude_hook_inbox";
+    session_id: string;
+    seat: string;
+    transcript_path?: string;
+} | {
+    route: "none";
+    code: "unsupported" | "wrong_pane" | "stale_binding";
+    reason: string;
+};
+/**
+ * Mission → session → runtime, from what each one signed: the runner's receipt names the session,
+ * Claude Code's registry says it runs and in which pane, and the adapter's file says this session
+ * loaded its hooks. The inbox belongs to this Unix account alone or it is not used.
+ */
+export declare function resolveRuntime(deps: RuntimeDeps, binding: {
+    session_id?: string;
+    pane_id?: string;
+    provider?: string;
+}): RuntimeRoute;
+export interface SteerEnvelope {
+    protocol: number;
+    steer: string;
+    grant: string;
+    session_id: string;
+    instruction: string;
+    instruction_sha256: string;
+    from: {
+        person_id?: string;
+        name?: string;
+        via?: string;
+    };
+    queued_at: string;
+    expires_at: string;
+    transcript_path?: string;
+    transcript_offset?: number;
+    /** A person decided this exact steer: the grant it cites no longer speaks for it. */
+    decided?: boolean;
+}
+/** The steer already on its way with these same words under this grant: one correction, one delivery. */
+export declare function sameInstructionInFlight(deps: RuntimeDeps, sessionId: string, grant: string, instruction: string): string | null;
+/**
+ * Put one correction in the session's inbox, durably: fsync, then one rename into pending/, so the
+ * adapter never reads half a file. The steer's id keeps it single across a retry or a connector restart.
+ */
+export declare function enqueueSteer(deps: RuntimeDeps, args: {
+    steer: string;
+    grant: string;
+    session_id: string;
+    instruction: string;
+    from: SteerEnvelope["from"];
+    grant_expires_at?: string;
+    decided?: boolean;
+    transcript_path?: string;
+    now?: Date;
+}): {
+    already: boolean;
+    file: string;
+    envelope: SteerEnvelope;
+};
+/**
+ * Revoke a grant or one steer for this session. The marker stops whatever the adapter would consume
+ * next, and what is still pending moves out at once. A rename decides any race with the adapter,
+ * so the answer is exact: revoked here, or already consumed.
+ */
+export declare function revokeInInbox(deps: RuntimeDeps, sessionId: string, target: {
+    grant: string;
+    steer?: string;
+}, reason: string): {
+    revoked: string[];
+    already_consumed: string[];
+};
+export interface DeliveryReceipt {
+    state: DeliveryState | "runtime_hook_emitted" | "seat_was_idle" | "seat_woken";
+    at?: string;
+    source: "connector" | "runtime_inbox" | "runtime_hook" | "claude_transcript" | "connector_clock" | "factory_runner";
+    detail?: Record<string, unknown>;
+}
+export interface SteerDelivery {
+    state: DeliveryState;
+    route: string;
+    session_id?: string;
+    receipts: DeliveryReceipt[];
+    /**
+     * While it waits, what will carry it: `next_tool_or_turn_end` for a working seat;
+     * `runner_wakes_idle_seat` for a seat already idle, which the factory runner's next pass prompts;
+     * `session_not_running` until a person resumes it, or it expires.
+     */
+    continuation?: "next_tool_or_turn_end" | "runner_wakes_idle_seat" | "session_not_running";
+    /** What the agent did after it received it, from its transcript. Whether that follows the correction is a person's judgment unless the steer named what to look for. */
+    next_actions?: {
+        at?: string;
+        tool: string;
+        input: string;
+    }[];
+    behavior?: "not_observed_yet" | "not_judged" | "expected_action_seen" | "expected_action_not_seen";
+    note: string;
+}
+interface TranscriptEvidence {
+    delivered?: {
+        at?: string;
+        attachment?: string;
+        hook_event?: string;
+        tool_use_id?: string;
+    };
+    acknowledged?: {
+        at?: string;
+        text: string;
+    };
+    next_actions: {
+        at?: string;
+        tool: string;
+        input: string;
+    }[];
+    actions_seen: number;
+    raw_inputs: string[];
+}
+/**
+ * What Claude Code itself recorded about this steer. Only an attachment naming the steer's id shows
+ * it entered the model's context, and only the agent's own later text can acknowledge it. Tool
+ * results and the agent's quotes of the id do not count as delivery.
+ */
+export declare function readTranscriptEvidence(path: string, offset: number, steer: string): TranscriptEvidence;
+/** Whether a prompt typed into the bound pane reached the session: Claude Code's own user or queued-prompt record. A pane echo proves nothing. */
+export declare function typedLineInTranscript(path: string, offset: number, instruction: string): {
+    at?: string;
+    record: string;
+} | null;
+/** Find a session's transcript when its adapter did not name it. */
+export declare function transcriptPathOf(deps: RuntimeDeps, sessionId: string): string | undefined;
+/**
+ * Where one steer stands, each state with its source and time, for request_session_steer,
+ * mission_status and get_run_result. It only reads, and it can be read at any time: ChatGPT
+ * disconnecting or the connector restarting changes nothing here.
+ */
+export declare function readSteerDelivery(deps: RuntimeDeps, record: {
+    id: string;
+    refs?: string[];
+    body: Record<string, unknown>;
+    completion_receipt?: Record<string, unknown> | undefined;
+}, now?: Date): SteerDelivery | null;
+/**
+ * What a forwarded steer's ledger record should now say, from its delivery: done once the model has
+ * it, stopped once it never will. Null while it is still on its way, or if it has already settled.
+ */
+export declare function settlementOf(deps: RuntimeDeps, record: {
+    id: string;
+    state?: string;
+    refs?: string[];
+    body: Record<string, unknown>;
+    completion_receipt?: Record<string, unknown> | undefined;
+}, now?: Date): {
+    state: "completed" | "blocked";
+    outcome: DeliveryState;
+    message: string;
+    at?: string;
+} | null;
+export {};