@agent-loom/loom 1.0.1 → 1.0.3

package/README.md

@@ -45,6 +45,58 @@ Apply the functions-dev template to this workspace
 
 The agent handles the whole workflow — searching, selecting, and applying the template to your workspace.
 
+## Launch an agent (`loom <agent>`)
+
+Once a template is applied (or in any workspace with `.github/agents/<id>.agent.md` files), start a single agent in your terminal:
+
+```bash
+# From inside a workspace (walks up to find .github/agents/)
+loom my-agent
+
+# Pass extra args through to the runtime after `--`
+loom my-agent -- --model=claude-sonnet-4.5
+
+# Or use the dedicated --model / --add-dir flags directly:
+loom my-agent --model=claude-sonnet-4.5
+
+# Launch from anywhere by pointing at a workspace
+loom my-agent --workspace /path/to/workspace
+
+# Launch an agent that isn't in any local workspace — stages it from a
+# configured registry into ~/.loom/sessions/<id>/workspace/
+loom some-registry-agent
+
+# Headless single-shot execution (no TTY): give a prompt, exit when done
+loom my-agent -p "investigate failing test" --no-interactive
+```
+
+The verb-less form (`loom <agent>`) is the **interactive** surface — it inherits
+your tty and lets you talk to the agent (mirrors the `copilot` CLI). For
+**scripted / structured** one-shot execution, use either the `loom run`
+subcommand or the `run()` SDK from `@agent-loom/loom/run`, both of which
+capture stdout, honor a hard timeout, and return structured results
+(`SESSION:`, `REPORT:`, `PROGRESS:` artifact paths).
+
+```bash
+# Run a template-instantiated agent headlessly and collect artifacts
+loom run my-template my-agent \
+  --prompt "what's broken?" \
+  --work-dir /tmp/loom-run-1 \
+  --timeout-ms 300000
+```
+
+Every launch is recorded under `~/.loom/sessions/<id>/`. Inspect past runs:
+
+```bash
+loom sessions list              # recent sessions
+loom sessions show <id>         # full metadata
+loom sessions tag <id> bug-repro
+loom sessions note <id> "this one reproduced #1234"
+```
+
+Escape hatches: `--no-session` (skip recording), `--no-registry-fallback`
+(disable the registry fallback), `--registry <name>` (restrict to one registry).
+
 ## Available Skills
 
 Loom ships with 5 skills that teach your coding agent how to use the system:
@@ -139,6 +191,23 @@ npm test
 node dist/cli.js --help
 ```
 
+### Working on a branch
+
+To dogfood a local build globally:
+
+```bash
+cd <your-loom-worktree>
+npm run build
+npm link                        # exposes `loom` from this worktree on PATH
+loom some-agent                 # uses your local build
+
+# When done:
+npm unlink -g @agent-loom/loom  # restore the published `loom`
+```
+
+`npm link` pins `loom` to the current worktree path. If you switch branches or
+blow away `node_modules`, re-run `npm run build` (no need to re-link).
+
 ## License
 
 ISC

package/dist/acp/client.d.ts

@@ -0,0 +1,182 @@
+export interface SpecialistSession {
+    sessionId: string;
+    agentId: string;
+    response: string;
+    activity: string;
+    plan: Array<{
+        content: string;
+        priority: string;
+        status: string;
+    }>;
+    toolCalls: Map<string, {
+        title: string;
+        status: string;
+    }>;
+    done: boolean;
+    stopReason: string | null;
+    startTime: number;
+}
+/**
+ * MCP server config consumed by `AcpClient.newSession` / `loadSession`.
+ *
+ * **Note:** This is intentionally distinct from the canonical
+ * `McpServerConfig` exported from `@agent-loom/loom` (which lives in
+ * `src/copilot/mcp.ts`). The two shapes differ — Copilot expects a map
+ * keyed by name with `env` as a `Record<string, string>`; ACP expects an
+ * array of entries with `name` as a field and `env` as `[{name,value}]`.
+ * Don't try to unify them — the divergence is in the underlying protocols.
+ */
+export interface AcpMcpServerConfig {
+    name: string;
+    command?: string;
+    args?: string[];
+    env?: Array<{
+        name: string;
+        value: string;
+    }>;
+    type?: string;
+    url?: string;
+}
+/**
+ * Discriminated update surfaced through `onSessionUpdate`. One callback sees
+ * every notification -- consumers filter by `type`. Text-only consumers
+ * (console, headless agents) care about `'message'`; chat consumers
+ * switch on all variants to render tool calls, thoughts, and plans.
+ */
+export type SessionUpdateEvent = {
+    type: 'message';
+    text: string;
+} | {
+    type: 'thought';
+    text: string;
+} | {
+    type: 'tool_call';
+    toolCallId: string;
+    title: string;
+    status: string;
+} | {
+    type: 'tool_update';
+    toolCallId: string;
+    status: string;
+    title?: string;
+} | {
+    type: 'plan';
+    entries: Array<{
+        content: string;
+        priority: string;
+        status: string;
+    }>;
+};
+export interface AcpClientOptions {
+    /** Path to an MCP config JSON file passed via `--additional-mcp-config @<path>`. */
+    additionalMcpConfigPath?: string;
+    /** Copilot CLI `--agent <id>` value. Selects the agent definition at spawn time. */
+    agentId?: string;
+    /**
+     * Per-protocol-call timeout in milliseconds. Applied to `initialize`,
+     * `newSession`, `loadSession`, and `prompt`. When a call exceeds the
+     * budget the returned promise rejects with `AcpTimeoutError` and the
+     * client is left for the caller to `dispose()`. `undefined` or `0`
+     * disables the timeout (default -- matches pre-0.x behaviour).
+     */
+    timeoutMs?: number;
+}
+/** Thrown when the child CLI exits or errors while a protocol call is in flight. */
+export declare class AcpConnectionClosedError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a protocol call exceeds its `timeoutMs` budget. */
+export declare class AcpTimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Drives an Agent Client Protocol (ACP) compatible CLI (e.g. `copilot --acp`)
+ * over stdio. Owns the child process, the JSON-RPC connection, and per-session
+ * state. One `AcpClient` instance = one child process; create multiple clients
+ * to run multiple CLIs in parallel.
+ *
+ * **Security posture (interim):** the client currently advertises
+ * `fs.readTextFile` / `fs.writeTextFile` capabilities unconditionally and
+ * auto-allows every `requestPermission`. This is safe for the trusted
+ * consumers shipping today (in-tree CLIs and the smoke script) but will not
+ * generalise. A pluggable `AcpClientOptions.policy` surface is being designed
+ * in serverless-paas-balam/loom#64 and will replace these defaults once the
+ * first external consumer lands.
+ *
+ * Typical flow:
+ *   const client = new AcpClient('copilot', { agentId: 'my-agent' });
+ *   await client.connect();
+ *   const session = await client.newSession('my-agent', cwd, mcpServers);
+ *   const unsubscribe = client.onSessionUpdate(session.sessionId, (u) => {
+ *       if (u.type === 'message') process.stdout.write(u.text);
+ *   });
+ *   await client.prompt(session.sessionId, 'Investigate X');
+ *   unsubscribe();
+ *   client.dispose();
+ */
+export declare class AcpClient {
+    private process;
+    private connection;
+    private sessions;
+    /** Per-session subscribers for full session update events. */
+    private updateSubscribers;
+    /**
+     * Tracks in-flight protocol calls (`connect`, `newSession`, `loadSession`,
+     * `prompt`) so we can reject them if the child process exits or errors
+     * before they complete. Without this, any caller awaiting the promise
+     * hangs forever on crash.
+     */
+    private inFlight;
+    private _isClosed;
+    private cliBin;
+    private opts;
+    /**
+     * @param cliBin Path or command name of the ACP-capable CLI (e.g. `copilot`).
+     * @param opts Constructor options. For back-compat a bare string in the
+     *   second position is treated as `additionalMcpConfigPath`.
+     */
+    constructor(cliBin: string, opts?: AcpClientOptions | string);
+    get isClosed(): boolean;
+    /**
+     * Spawn the CLI with `--acp`, wire up the ACP JSON-RPC stream, and complete
+     * protocol initialization. Must be called before any session operation.
+     * Throws if the client has already connected or been disposed -- one
+     * `AcpClient` instance owns exactly one child process for its lifetime.
+     */
+    connect(): Promise<void>;
+    /** Create a new session rooted at `cwd` with the given MCP servers. */
+    newSession(agentId: string, cwd: string, mcpServers: AcpMcpServerConfig[]): Promise<SpecialistSession>;
+    /**
+     * Resume an existing CLI session by ID. Requires `loadSession` capability.
+     * Throws on failure -- callers should fall back to `newSession()`.
+     */
+    loadSession(sessionId: string, agentId: string, cwd: string, mcpServers: AcpMcpServerConfig[]): Promise<SpecialistSession>;
+    /**
+     * Send a prompt to an existing session and block until the turn completes.
+     * Live deltas arrive via `onSessionUpdate` subscribers during the await.
+     * Rejects with `AcpConnectionClosedError` if the child exits mid-turn.
+     */
+    prompt(sessionId: string, text: string): Promise<SpecialistSession>;
+    /** Cancel an in-flight prompt on the given session. Safe if already closed. */
+    cancelSession(sessionId: string): Promise<void>;
+    getSession(sessionId: string): SpecialistSession | undefined;
+    /**
+     * Subscribe to all session updates (message/thought chunks, tool calls,
+     * plans) for one session. Consumers filter by `event.type`.
+     */
+    onSessionUpdate(sessionId: string, cb: (event: SessionUpdateEvent) => void): () => void;
+    /** Kill the child process and release all state. Idempotent. */
+    dispose(): void;
+    /**
+     * Wrap a protocol promise so that if the child process ends before it
+     * settles, the returned promise rejects instead of hanging. When
+     * `opts.timeoutMs` is set, also rejects with `AcpTimeoutError` after the
+     * configured budget.
+     */
+    private withInFlight;
+    /** Invoked on child exit, process error, or ACP stream close. Idempotent. */
+    private handleProcessEnd;
+    private emit;
+    private createClient;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/acp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/acp/client.ts"],"names":[],"mappings":"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"}