@parlor/agent-host 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cychien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @parlor/agent-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Parlor Host, the `parlor-host` command: it connects the coding agents on a computer, such as Claude Code and Codex, to a Parlor app's sidebar. `parlor dev` runs it for you; with sign-in, a user connects their computer with `npx @parlor/agent-host connect <app url>`. Installed by `@parlor/cli`; you do not depend on it directly.
+
+```sh
+npx @parlor/agent-host connect https://todos.example.com
+```
+
+Tests can script an agent with the fake agent:
+
+```ts
+import type { FakeAgentScript } from "@parlor/agent-host/testing";
+
+export const script: FakeAgentScript = { steps: {}, fallback: "echo" };
+```
+
+Docs: https://cychien.github.io/parlor/guides/agent-sidebar/

package/dist/acp.d.ts

@@ -0,0 +1,165 @@
+import type { AgentProfile } from "./agents.js";
+/**
+ * The only file that knows ACP. The v1 adapter speaks ndjson over stdio through
+ * `@agentclientprotocol/sdk`; an ACP v2 or HTTP-transport agent implements the same
+ * port. No ACP type crosses this file.
+ */
+export interface AgentLauncher {
+    /** Spawns the profile (never through a shell), runs `initialize`, reports problems. */
+    launch(profile: AgentProfile, options: LaunchOptions): Promise<AgentConnection>;
+}
+export interface LaunchOptions {
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+}
+export interface AgentConnection {
+    readonly capabilities: AgentCapabilities;
+    openSession(input: OpenSessionInput): Promise<AgentSession>;
+    readonly exited: Promise<AgentExit>;
+    /** Kills the whole process group. */
+    kill(): Promise<void>;
+}
+/** `openSession` would not run the session; `leftOpen` when the agent still holds it. */
+export declare class SessionRefused extends Error {
+    readonly leftOpen: boolean;
+    readonly name = "SessionRefused";
+    constructor(message: string, leftOpen: boolean, options?: ErrorOptions);
+}
+export interface AgentCapabilities {
+    readonly resume: boolean;
+    readonly close: boolean;
+    readonly mcpHttp: boolean;
+    /** False until the user logs the agent in on a terminal; `problem` says how. */
+    readonly ready: boolean;
+    readonly problem?: string | undefined;
+}
+export interface OpenSessionInput {
+    readonly cwd: string;
+    readonly mcpServers: readonly StdioMcpServer[];
+    readonly resume?: string | undefined;
+    /** A remote turn never runs in a bypass mode. */
+    readonly pinAskMode: boolean;
+    readonly strictAsk?: boolean | undefined;
+}
+export interface StdioMcpServer {
+    readonly name: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+export interface AgentSession {
+    readonly id: string;
+    readonly resumed: boolean;
+    /**
+     * Every update reaches `handlers.update` synchronously and in wire order, and the
+     * promise settles only after the last one: the stop is queued behind its chunks.
+     */
+    prompt(blocks: readonly PromptBlock[], handlers: TurnHandlers): Promise<StopReason>;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+}
+export type PromptBlock = {
+    readonly kind: "text";
+    readonly text: string;
+};
+export type StopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+export interface TurnHandlers {
+    update(update: AgentUpdate): void;
+    ask(ask: AgentAsk): Promise<AgentAskAnswer>;
+}
+export type ToolKind = "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "switch_mode" | "other";
+export interface McpToolRef {
+    readonly server: string;
+    readonly tool: string;
+}
+export type AgentUpdate = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "thought";
+    readonly text: string;
+} | {
+    readonly kind: "tool_start";
+    readonly toolCallId: string;
+    readonly title: string;
+    readonly toolKind: ToolKind;
+    readonly mcp?: McpToolRef | undefined;
+} | {
+    readonly kind: "tool_update";
+    readonly toolCallId: string;
+    readonly title?: string | undefined;
+    readonly status?: "pending" | "in_progress" | "completed" | "failed" | undefined;
+    readonly detail?: string | undefined;
+} | {
+    readonly kind: "plan";
+    readonly entries: readonly {
+        readonly content: string;
+        readonly status: "pending" | "in_progress" | "completed";
+    }[];
+} | {
+    readonly kind: "mode";
+    readonly modeId: string;
+};
+export type AskEffect = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+export type AgentAsk = {
+    readonly kind: "permission";
+    readonly toolCallId: string;
+    readonly title: string;
+    readonly toolKind: ToolKind;
+    readonly mcp?: McpToolRef | undefined;
+    readonly options: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly effect: AskEffect;
+    }[];
+} | {
+    readonly kind: "question";
+    readonly message: string;
+    readonly schema: Readonly<Record<string, unknown>>;
+};
+export type AgentAskAnswer = {
+    readonly kind: "selected";
+    readonly optionId: string;
+} | {
+    readonly kind: "values";
+    readonly values: Readonly<Record<string, string | number | boolean>>;
+} | {
+    readonly kind: "declined";
+} | {
+    readonly kind: "cancelled";
+};
+export type AgentExit = {
+    readonly kind: "killed";
+} | {
+    readonly kind: "exited";
+    readonly code: number | null;
+    readonly stderrTail: string;
+};
+/** The bytes an ACP peer reads and writes: a child's stdio, or a test's pipe. */
+export interface AcpStdio {
+    readonly input: ReadableStream<Uint8Array>;
+    readonly output: WritableStream<Uint8Array>;
+}
+export interface AgentModes {
+    readonly current: string;
+    readonly available: readonly string[];
+}
+/** The agent side of ACP in this file's own terms, for the fake agent. */
+export interface AcpAgentHandlers {
+    readonly capabilities: Pick<AgentCapabilities, "resume" | "close" | "mcpHttp">;
+    newSession(input: OpenSessionInput): Promise<{
+        readonly id: string;
+        readonly modes?: AgentModes | undefined;
+    }>;
+    prompt(sessionId: string, blocks: readonly PromptBlock[], peer: {
+        update(update: AgentUpdate): Promise<void>;
+        ask(ask: AgentAsk): Promise<AgentAskAnswer>;
+        readonly cancelled: AbortSignal;
+    }): Promise<StopReason>;
+}
+/** ACP v1 over stdio. */
+export declare function acpLauncher(): AgentLauncher;
+/** Serves `handlers` as an ACP agent on `io`, until the other side hangs up. */
+export declare function serveAcpAgent(handlers: AcpAgentHandlers, io: AcpStdio): Promise<void>;
+//# sourceMappingURL=acp.d.ts.map

package/dist/acp.d.ts.map

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