@ocis/myagent-cli 0.2.0

package/dist/agent/prompt-builder.d.ts

@@ -0,0 +1,9 @@
+export interface PromptBuilderOptions {
+    workspace: string;
+    skillDirs: string[];
+    /** Skip AGENTS.md / CLAUDE.md discovery (--no-context-files). */
+    noContextFiles?: boolean;
+    extraInstructions?: string;
+}
+/** Returns a `buildSystemPrompt()` function for AgentRunnerOptions. */
+export declare function createSystemPromptBuilder(opts: PromptBuilderOptions): () => Promise<string>;

package/dist/agent/prompt-builder.js

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// Shared system-prompt builder for the interactive and headless runners.
+//
+// Both entry points ship the same block: context files discovered on the
+// machine, environment facts (workspace + OS), the local skills catalog and
+// the static mode protocol. The block is deliberately independent
+// of the active mode and other per-turn state (todos, git branch, date) so it
+// stays byte-identical across turns and the provider prompt cache holds.
+// ---------------------------------------------------------------------------
+import { composeSystemPrompt, findContextFiles, osDescription } from "./context.js";
+import { buildSkillsCatalog, discoverSkills } from "../skills/discovery.js";
+import { globalContextPath } from "../config.js";
+/** Returns a `buildSystemPrompt()` function for AgentRunnerOptions. */
+export function createSystemPromptBuilder(opts) {
+    return async () => {
+        const contextFiles = opts.noContextFiles
+            ? []
+            : await findContextFiles(opts.workspace, globalContextPath());
+        const skills = await discoverSkills(opts.skillDirs);
+        return composeSystemPrompt({
+            workspace: opts.workspace,
+            contextFiles,
+            environment: {
+                workspace: opts.workspace,
+                os: osDescription(),
+            },
+            skillsCatalog: buildSkillsCatalog(skills),
+            extraInstructions: opts.extraInstructions,
+        });
+    };
+}

package/dist/agent/sessions.d.ts

@@ -0,0 +1,38 @@
+import type { TodoItem } from "./todo.js";
+export interface LocalSessionEntry {
+    id: string;
+    title: string;
+    updatedAt: number;
+    todos?: TodoItem[];
+}
+export interface LocalSessionIndexData {
+    [cwd: string]: {
+        last?: string;
+        sessions: LocalSessionEntry[];
+    };
+}
+export declare class SessionIndex {
+    private readonly path;
+    private data;
+    constructor(path: string, data?: LocalSessionIndexData);
+    static load(path: string): Promise<SessionIndex>;
+    private bucket;
+    /** Record/refresh a thread for a working directory and mark it most recent. */
+    remember(cwd: string, threadId: string, title: string): void;
+    lastThread(cwd: string): string | undefined;
+    get(cwd: string, threadId: string): LocalSessionEntry | undefined;
+    list(cwd: string): LocalSessionEntry[];
+    /** Thread ids this machine has seen for a working directory. */
+    knownThreadIds(cwd: string): Set<string>;
+    /** Reverse lookup: which working directory recorded this thread. */
+    findCwd(threadId: string): string | undefined;
+    setTitle(cwd: string, threadId: string, title: string): void;
+    setTodos(cwd: string, threadId: string, todos: TodoItem[]): void;
+    forget(cwd: string, threadId: string): void;
+    /** Fire-and-forget persistence, serialized so concurrent updates can't interleave. */
+    save(): Promise<void>;
+    private saveChain;
+    private write;
+}
+/** Derive a session title from the first user message (locally, before PATCH). */
+export declare function deriveTitle(message: string): string;

package/dist/agent/sessions.js

@@ -0,0 +1,130 @@
+// ---------------------------------------------------------------------------
+// Local session index: cwd → known remote threads (+ per-thread TODO lists).
+//
+// The remote session is the source of truth for history; this file only
+// remembers which thread belongs to which working directory so `-c`/`-r`
+// resume the right conversation. Never contains credentials.
+// ---------------------------------------------------------------------------
+import { mkdir, rename } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileExists, readJsonFile, writeFile } from "../runtime.js";
+export class SessionIndex {
+    path;
+    data;
+    constructor(path, data = {}) {
+        this.path = path;
+        this.data = data;
+    }
+    static async load(path) {
+        try {
+            if (!(await fileExists(path)))
+                return new SessionIndex(path);
+            const parsed = await readJsonFile(path);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return new SessionIndex(path);
+            // Normalize instead of trusting the persisted shape: a truncated write
+            // or a manual edit can leave a bucket without a valid `sessions` array,
+            // which would crash the first remember()/list() on that cwd.
+            const data = {};
+            for (const [cwd, bucket] of Object.entries(parsed)) {
+                if (!bucket || typeof bucket !== "object")
+                    continue;
+                data[cwd] = {
+                    last: typeof bucket.last === "string" ? bucket.last : undefined,
+                    sessions: Array.isArray(bucket.sessions)
+                        ? bucket.sessions.filter((s) => s && typeof s === "object" && typeof s.id === "string")
+                        : [],
+                };
+            }
+            return new SessionIndex(path, data);
+        }
+        catch {
+            return new SessionIndex(path);
+        }
+    }
+    bucket(cwd) {
+        return (this.data[cwd] ??= { sessions: [] });
+    }
+    /** Record/refresh a thread for a working directory and mark it most recent. */
+    remember(cwd, threadId, title) {
+        const bucket = this.bucket(cwd);
+        const existing = bucket.sessions.find((s) => s.id === threadId);
+        const entry = existing
+            ? { ...existing, title: title || existing.title, updatedAt: Date.now() }
+            : { id: threadId, title, updatedAt: Date.now() };
+        // Move to the front (recency order) — no timestamp sorting, which would be
+        // non-deterministic for same-millisecond updates.
+        bucket.sessions = [entry, ...bucket.sessions.filter((s) => s.id !== threadId)].slice(0, 50);
+        bucket.last = threadId;
+        void this.save();
+    }
+    lastThread(cwd) {
+        return this.data[cwd]?.last;
+    }
+    get(cwd, threadId) {
+        return this.data[cwd]?.sessions.find((s) => s.id === threadId);
+    }
+    list(cwd) {
+        return [...(this.data[cwd]?.sessions ?? [])];
+    }
+    /** Thread ids this machine has seen for a working directory. */
+    knownThreadIds(cwd) {
+        return new Set((this.data[cwd]?.sessions ?? []).map((s) => s.id));
+    }
+    /** Reverse lookup: which working directory recorded this thread. */
+    findCwd(threadId) {
+        for (const [cwd, bucket] of Object.entries(this.data)) {
+            if (bucket.sessions.some((s) => s.id === threadId))
+                return cwd;
+        }
+        return undefined;
+    }
+    setTitle(cwd, threadId, title) {
+        const entry = this.get(cwd, threadId);
+        if (entry) {
+            entry.title = title;
+            void this.save();
+        }
+    }
+    setTodos(cwd, threadId, todos) {
+        const entry = this.get(cwd, threadId);
+        if (entry) {
+            entry.todos = todos;
+            void this.save();
+        }
+    }
+    forget(cwd, threadId) {
+        const bucket = this.data[cwd];
+        if (!bucket)
+            return;
+        bucket.sessions = bucket.sessions.filter((s) => s.id !== threadId);
+        if (bucket.last === threadId)
+            bucket.last = bucket.sessions[0]?.id;
+        void this.save();
+    }
+    /** Fire-and-forget persistence, serialized so concurrent updates can't interleave. */
+    save() {
+        this.saveChain = this.saveChain
+            .then(() => this.write())
+            .catch(() => { });
+        return this.saveChain;
+    }
+    saveChain = Promise.resolve();
+    async write() {
+        await mkdir(dirname(this.path), { recursive: true });
+        // Per-write unique temp name: two CLI processes sharing the index (two
+        // terminal windows) would otherwise interleave on one fixed `.tmp` path
+        // and could rename a half-written file over the index.
+        const tmp = `${this.path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+        await writeFile(tmp, JSON.stringify(this.data, null, 2) + "\n");
+        await rename(tmp, this.path);
+    }
+}
+/** Derive a session title from the first user message (locally, before PATCH). */
+export function deriveTitle(message) {
+    const firstLine = message.trim().split("\n")[0] ?? "";
+    const clean = firstLine.replace(/\s+/g, " ").trim();
+    if (!clean)
+        return "Untitled";
+    return clean.length > 60 ? `${clean.slice(0, 57)}…` : clean;
+}

package/dist/agent/todo.d.ts

@@ -0,0 +1,18 @@
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export interface TodoItem {
+    content: string;
+    status: TodoStatus;
+}
+/** Parse/validate the tool's `todos` argument. Throws with a model-readable message. */
+export declare function parseTodoItems(value: unknown): TodoItem[];
+export declare class TodoStore {
+    private items;
+    private listeners;
+    list(): readonly TodoItem[];
+    get doneCount(): number;
+    get current(): TodoItem | undefined;
+    replace(items: TodoItem[]): void;
+    onChanged(listener: () => void): () => void;
+    toJSON(): TodoItem[];
+    static fromJSON(value: unknown): TodoStore;
+}

package/dist/agent/todo.js

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// Per-session TODO list, driven by the local_update_todo client tool.
+//
+// In-memory with a change listener for the TUI panel; the session index
+// persists it so resume restores the same list. The agent is instructed to
+// send the ENTIRE list on every update (same contract as myagent-studio).
+// ---------------------------------------------------------------------------
+const VALID_STATUSES = ["pending", "in_progress", "completed"];
+/** Parse/validate the tool's `todos` argument. Throws with a model-readable message. */
+export function parseTodoItems(value) {
+    if (!Array.isArray(value))
+        throw new Error("`todos` must be an array of {content, status} items.");
+    return value.map((raw, index) => {
+        if (typeof raw !== "object" || raw === null)
+            throw new Error(`todos[${index}] must be an object.`);
+        const item = raw;
+        if (typeof item.content !== "string" || !item.content.trim()) {
+            throw new Error(`todos[${index}].content must be a non-empty string.`);
+        }
+        if (typeof item.status !== "string" || !VALID_STATUSES.includes(item.status)) {
+            throw new Error(`todos[${index}].status must be one of: ${VALID_STATUSES.join(", ")}.`);
+        }
+        return { content: item.content.trim(), status: item.status };
+    });
+}
+export class TodoStore {
+    items = [];
+    listeners = new Set();
+    list() {
+        return this.items;
+    }
+    get doneCount() {
+        return this.items.filter((t) => t.status === "completed").length;
+    }
+    get current() {
+        return this.items.find((t) => t.status === "in_progress")
+            ?? this.items.find((t) => t.status === "pending");
+    }
+    replace(items) {
+        this.items = items;
+        for (const listener of this.listeners)
+            listener();
+    }
+    onChanged(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    toJSON() {
+        return this.items;
+    }
+    static fromJSON(value) {
+        const store = new TodoStore();
+        if (Array.isArray(value)) {
+            try {
+                store.items = parseTodoItems(value);
+            }
+            catch { /* ignore corrupt persisted list */ }
+        }
+        return store;
+    }
+}

package/dist/agent/turn.d.ts

@@ -0,0 +1,309 @@
+import type { IntegrationClient } from "../protocol/client.js";
+import type { AgentUsage, ClientToolCall, ServerToolEvent, SessionDetail } from "../protocol/types.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { AgentMode } from "./modes.js";
+import type { TodoStore } from "./todo.js";
+import type { ApprovalPolicy } from "../approval/policy.js";
+export type RunState = "idle" | "running" | "stopping";
+/** True for event-channel failures retrying cannot fix (bad key, deleted session). */
+export declare function isPermanentEventChannelError(err: unknown): boolean;
+export interface TurnCallbacks {
+    onUserMessage: (text: string, queued: boolean) => void;
+    /**
+     * A message submitted while a run is active. It is NOT part of the
+     * conversation yet — the UI floats it above the prompt until the agent
+     * actually injects it (onSteerAccepted) or it is delivered as a fresh turn
+     * (onUserMessage then releases the float).
+     */
+    onSteerQueued?: (text: string) => void;
+    /**
+     * A steered message is now part of the conversation (the agent injected it,
+     * or the turn ended with it persisted) — release the float and render it as
+     * a transcript user message.
+     */
+    onSteerAccepted?: (text: string) => void;
+    onContent: (delta: string, messageId?: string) => void;
+    onReasoning: (delta: string) => void;
+    onUsage: (usage: AgentUsage) => void;
+    onServerTool: (tool: ServerToolEvent) => void;
+    onToolStart: (call: ClientToolCall, summary: string) => void;
+    onToolEnd: (call: ClientToolCall, output: string, isError: boolean) => void;
+    onNotice: (text: string, level: "info" | "error" | "warn", code?: string) => void;
+    onRunState: (state: RunState) => void;
+    onThread: (threadId: string) => void;
+    onSession: (detail: SessionDetail) => void;
+}
+export interface AgentRunnerOptions {
+    client: IntegrationClient;
+    registry: ToolRegistry;
+    workspace: string;
+    allowOutside: boolean;
+    skillDirs: string[];
+    todos: TodoStore;
+    approval: ApprovalPolicy;
+    /** Compose the (mode-independent) per-request system block. */
+    buildSystemPrompt: () => Promise<string>;
+    callbacks: TurnCallbacks;
+    /** Override the event-channel reconnect delay (tests). */
+    eventReconnectDelayMs?: number;
+}
+export declare class AgentRunner {
+    private readonly opts;
+    threadId: string | null;
+    mode: AgentMode;
+    /** undefined = omit thinkingLevel (provider default). */
+    thinkingLevel: string | undefined;
+    /**
+     * The model the user picked for the next new thread (null = client-choice
+     * default). Sent only on a new thread's first run: the server pins the
+     * thread's model on its first run, and a later request naming a different
+     * model on the same thread is rejected with 400.
+     */
+    selectedModel: string | null;
+    /**
+     * Effective model of the current/resumed thread, as reported by the server.
+     * Display only — selection goes through `selectedModel`.
+     */
+    model: string | null;
+    usage: AgentUsage | null;
+    state: RunState;
+    private abort;
+    /**
+     * True from stop() until the next run starts — the cancelled-approval
+     * wording keys off it (the AbortController is nulled by run()'s finally
+     * before an in-flight round resumes, so it cannot be used there).
+     */
+    private stopped;
+    private followUps;
+    /**
+     * Chain of fire-and-forget follow-up turns (user follow-ups).
+     * `waitForIdle()` awaits it so headless runs don't exit before a queued
+     * turn has been delivered.
+     */
+    private followUpChain;
+    /**
+     * Tool calls already reported as released — populated from the run stream's
+     * `TOOL_CALL_RESULT(isError)` echoes, `RUN_FINISHED` with calls still
+     * pending, and the fallback event channel. Also the client-side idempotency
+     * filter: a replayed CUSTOM_TOOL_CALL for an abandoned call is never
+     * executed again.
+     */
+    private abandonedToolCalls;
+    /**
+     * Every CUSTOM_TOOL_CALL id received this session. The replay guard: an id
+     * seen once is never enqueued again, whatever the delivery path (run stream,
+     * event-channel replay) — a duplicate would execute a side-effecting tool
+     * twice. Cumulative like abandonedToolCalls: ids are unique per call, so
+     * there is nothing to reset.
+     */
+    private seenToolCallIds;
+    /**
+     * Unix ms of a server-reported interruption of the previous run (restart /
+     * idle scale-down) — wording only: released calls are explained as an
+     * interruption instead of an ordinary no-response release.
+     */
+    private lastRunInterruptedAt;
+    /**
+     * Calls received from the agent but not yet submitted: the release filter.
+     * An id is removed BEFORE its submission request goes out, so the server's
+     * echo of our own result can never be misread as a release.
+     */
+    private pendingSubmission;
+    /**
+     * Steers acked but not yet injected into the run, keyed by the persisted
+     * message id (from INPUT_ACCEPTED). The ack only means "persisted + queued
+     * for injection" — the float stays up until QUEUED_MESSAGE_DELIVERED (the
+     * agent actually put the message into the conversation) releases it. The
+     * turn-end sweep releases whatever is left: unconsumed steers are re-issued
+     * as a fresh prompt by the manager, and the message is in the session
+     * either way, so the float must not linger.
+     */
+    private pendingSteerDeliveries;
+    /**
+     * Tool rounds scheduled or executing (debounce included). The turn drains
+     * them before it settles, so a round is never raced by the followUps drain.
+     */
+    private roundsInFlight;
+    private roundsDrained;
+    /**
+     * True once the current run segment ended (RUN_FINISHED/RUN_ERROR) — a
+     * stream that closes without this observed a drop, not a settle.
+     */
+    private runSettled;
+    /**
+     * True while a channel-loss notice is outstanding (cleared when events flow
+     * again) — keeps "lost the event channel" to one notice per outage.
+     */
+    private eventChannelDown;
+    /** Fallback event-channel subscription (reconcile window only). */
+    private eventsAbort;
+    /**
+     * Mode last announced to the server. null = unknown (new/resumed thread), so
+     * the next message carries `[mode: x]`. Kept in sync by the send paths.
+     */
+    private announcedMode;
+    constructor(opts: AgentRunnerOptions);
+    get busy(): boolean;
+    setMode(mode: AgentMode): void;
+    /** Forget the announced mode (new thread or resume) — re-announce on next send. */
+    resetModeAnnouncement(): void;
+    setThinkingLevel(level: string | undefined): void;
+    /** Select the model for the next new thread (null = server default). */
+    setModel(model: string | null): void;
+    /** Advertised tools are mode-independent: a stable schema keeps the prompt cache warm. */
+    private toolDefs;
+    /** Tool definitions in AG-UI protocol shape (name/description/parameters). */
+    private aguiToolDefs;
+    /**
+     * The user text to send, prefixed with `[mode: x]` when the mode changed
+     * since the last send (or was never announced). Also returns the mode being
+     * announced so the caller can record it after a successful send. The marker
+     * is the only mode signal the model gets — the system prompt describes both
+     * modes statically.
+     */
+    private announcedText;
+    private toolContext;
+    /**
+     * Compose a send's input messages: the per-request system block (when one is
+     * built) plus the user message with its `[mode: x]` marker applied. Shared by
+     * the steer and run paths so their mode-announcement semantics cannot drift.
+     */
+    private composeInput;
+    /**
+     * Send a user message. While a run is active:
+     *  - default: steered into the in-flight run (POST .../messages)
+     *  - `followUp`: queued locally and delivered after the run settles
+     */
+    send(text: string, opts?: {
+        followUp?: boolean;
+    }): Promise<void>;
+    /** Force-stop the run (used by Esc and /stop). */
+    stop(): Promise<void>;
+    /** Manually compact the remote session history. */
+    compact(): Promise<void>;
+    /** Refresh model/usage/thinking metadata from the server. */
+    refreshSession(includeHistory?: boolean): Promise<SessionDetail | null>;
+    private run;
+    /**
+     * Wait for every in-flight tool round (or an abort, so /stop never hangs on
+     * a pending approval).
+     */
+    private drainRounds;
+    /**
+     * Open the run stream and dispatch its events until it closes. Returns when
+     * the stream ended; `runSettled` distinguishes a clean settle from a drop.
+     */
+    private streamRun;
+    /**
+     * One AG-UI event from the run stream. Terminal events drive release
+     * detection and the settle flag; `CUSTOM_TOOL_CALL` events feed the
+     * debounced execution round.
+     */
+    private handleRunEvent;
+    private applyUsage;
+    /** Report every call still awaiting submission as released (run ended). */
+    private releasePending;
+    /** Release the float for a steer the agent actually injected (swap to a
+     *  transcript bubble). Unknown ids (another client's steer) are ignored. */
+    private releaseSteer;
+    /** Release every float still pending — the turn ended before the agent
+     *  injected the message (settled, dropped, stopped, errored). The message
+     *  is persisted in the session either way, so the float must not linger. */
+    private releasePendingSteers;
+    /**
+     * Execute a round's client tool calls (approval + plan-mode refusal) and
+     * deliver the results. Runs off the event dispatcher: the run stream stays
+     * attached throughout, so release/continuation events keep flowing while a
+     * human decides.
+     */
+    private executeAndSubmit;
+    /**
+     * Resolve once the runner is idle and every queued follow-up turn has been
+     * delivered. Headless runs await this before exiting so a queued turn is
+     * never cut off by process exit.
+     */
+    waitForIdle(): Promise<void>;
+    /**
+     * Deliver a round's tool results, reconciling against the server's truth
+     * first when it advertises `toolCallExpiry`:
+     *
+     *  - still pending (exact id) → submit as-is (native tool result, same run);
+     *  - the model retried the same action (same name + canonical args) → adopt
+     *    the retry's id and submit the already-executed result (no double side
+     *    effect);
+     *  - other pending calls the client never executed → run them through the
+     *    normal approval+execution path and submit their results too;
+     *  - outputs with no matching pending call → the server already released
+     *    the call; the result is discarded (the agent moved on when the call
+     *    was released — a follow-up message would only confuse it).
+     *
+     * A submission that still races a release (pre-stream 400 or the
+     * INPUT_REJECTED frame) re-reconciles once.
+     */
+    private submitRound;
+    /**
+     * Compare a round's outputs against the server's pending list. Returns the
+     * outputs that can still be delivered (exact ids + adopted retries + newly
+     * executed pending calls) and the ones whose calls the server already
+     * released (discarded by the caller).
+     */
+    private reconcileRound;
+    /**
+     * Discard results whose calls the server already released. The agent
+     * answered those calls when they were released — delivering the result now
+     * (as a follow-up message) would only confuse it. The release itself was
+     * usually already surfaced (run stream / channel); only announce the
+     * discard when this is the first the user hears of it.
+     */
+    private discardReleasedResults;
+    /** Human reason for a released call, preferring a known server restart. */
+    private releaseReason;
+    /**
+     * Mark calls as released and tell the user once. Only calls this turn is
+     * actually waiting on are surfaced (a result for an older call arriving on
+     * the stream/channel is not actionable) — `force` is for ids the server
+     * itself reported as expired, which have already left the pending set.
+     */
+    private markAbandoned;
+    private latchThread;
+    /** Open the session event subscription for the recovery window (capability-gated). */
+    private startEventSubscription;
+    private stopEventSubscription;
+    /**
+     * Subscribe → reconnect loop. Bounded (see MAX_EVENT_RECONNECTS) and stopped
+     * as soon as the outstanding call is known to be released, so a paused
+     * sandbox is woken at most a few times and never kept awake by the channel.
+     *
+     * Loss and exhaustion are surfaced (once each, state change only): a long
+     * approval wait can outlive the sandbox, and the user staring at the
+     * approval card deserves to know the channel went away.
+     */
+    private runEventSubscription;
+    /**
+     * Handle one fallback-channel event. The channel is subscribed only when no
+     * run stream is attached (the recovery window), so an idle snapshot or a
+     * terminal run event means the calls still awaiting submission were
+     * released. Echoes of our own submissions are already out of
+     * `pendingSubmission` and can never be read as releases.
+     */
+    private handleSessionEvent;
+    private parseCall;
+    /** Read-only calls run concurrently; mutating and unknown calls serialize. */
+    private executeToolCalls;
+    /**
+     * Execute one client tool call. Returns null when the call was cancelled
+     * (server released it, or the run was stopped while the user decided): the
+     * tool never ran and nothing may be submitted for it.
+     */
+    private executeOne;
+    /**
+     * The run stream died before the run settled. Reconcile against the durable
+     * session: if the backend is waiting on tool calls, re-run READ-ONLY ones
+     * (safe) and fail mutating ones rather than re-applying side effects
+     * silently. The event channel watches for a release while the round is
+     * finished (no request stream is attached in this window).
+     */
+    private reconcile;
+}
+/** Convert persisted session usage into the live-usage shape the UI renders. */
+export declare function usageFromSession(usage: SessionDetail["usage"]): AgentUsage | null;