@intentius/chant-lexicon-fountain 0.56.0 → 0.58.0

package/README.md

@@ -5,15 +5,17 @@ fountain lexicon plugin for [chant](https://github.com/intentius/chant).
 [fountain](https://github.com/BinaryBourbon/fountain) runs coding agents in
 sandboxed VMs. This lexicon declares its workload layer as typed chant
 resources: `Environment` (sandbox baseline), `Vault` (env-var overrides),
-`Agent` (a runnable agent config). Conversations are runs, not resources —
-start them with the `fountainRun` op.
+`Agent` (a runnable agent config), `Teammate` (an agent seated on the team,
+with a thread of its own), `Schedule` (a cron prompt into that thread), and
+`Webhook` (where the estate's events leave it). Conversations are runs, not
+resources — start them with the `fountainRun` op.
 
 `chant build` serializes to fountain's own manifest YAML (`fountain apply -f`
 accepts it verbatim) — the same YAML `fountainApply` sends to fountain's bulk
 `POST /api/apply` endpoint in one request.
 
 ```ts
-import { Environment, Agent } from "@intentius/chant-lexicon-fountain";
+import { Environment, Agent, Teammate, Schedule } from "@intentius/chant-lexicon-fountain";
 
 export const env = new Environment({
   name: "team-env",
@@ -28,8 +30,22 @@ export const helper = new Agent({
   runtime: "claude",
   environment: env,                              // typed ref — dangling name = build error
 });
+
+export const helperSeat = new Teammate({ name: "helper", agent: helper });
+
+export const nightly = new Schedule({
+  name: "nightly-converge",
+  teammate: helperSeat,
+  cron: "0 3 * * *",                             // five fields, UTC (FTN020)
+  prompt: "chant run converge",
+});
 ```
 
+`runtime: "acp"` and `runtime_command` are on the generated `Agent` type as
+chant extensions. Upstream does not have them until
+[BinaryBourbon/fountain#1634](https://github.com/BinaryBourbon/fountain/pull/1634)
+lands, and an instance without that PR rejects the pair at apply.
+
 For agents handling anything sensitive, `ConciergeStack` bundles the
 locked-down defaults (deny-all egress, no vault overrides, ownership marker
 on both resources) so loosening any of them is a visible, reviewable
@@ -61,7 +77,7 @@ left unmodeled.
 - `src/plugin.ts` — LexiconPlugin with all lifecycle methods
 - `src/serializer.ts` — manifest YAML output
 - `src/codegen/`, `src/spec/` — generation pipeline and spec fetch/parse
-- `src/lint/rules/`, `src/lint/post-synth/` — FTN001 (AST) and FTN010–017
+- `src/lint/rules/`, `src/lint/post-synth/` — FTN001 (AST) and FTN010 to FTN023
 - `src/op/activities/` — `fountainApply` (reconciler) and `fountainRun`
 - `src/composites/` — `ConciergeStack`
 - `src/skills/` — agent skills for authoring, secrets, and locked sandboxes

package/dist/acp/command-line.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A prompt is a chant command line (#2125).
+ *
+ * That is the whole convention, and the reason a fountain thread reads as an
+ * environment's shell history: each turn is `chant run prod-apply --env prod`
+ * or `chant lifecycle diff --live`, so scrolling the thread is scrolling what
+ * was done to the environment.
+ *
+ * It is a *command line*, not a shell line. This module splits on whitespace
+ * with quote awareness and stops there: no expansion, no substitution, no
+ * pipes, no `&&`, no globbing, no `$VAR`. A prompt that does not parse to a
+ * chant verb is refused before anything runs, which is what keeps an agent
+ * that can be prompted by anyone from being an agent that can run anything.
+ * The verb list is core's own registry, so the set of things this accepts is
+ * exactly the set `chant --help` prints.
+ */
+import type { ParsedArgs, CommandDef } from "@intentius/chant/cli/registry";
+/**
+ * Split a command line into argv the way a shell would *quote* it, and in no
+ * other way.
+ *
+ * Single and double quotes group, a backslash escapes the next character
+ * inside double quotes and outside them, and nothing else is special. An
+ * unterminated quote is an error rather than a silent join, because the
+ * silent reading changes which arguments a verb receives.
+ */
+export declare function tokenize(text: string): string[];
+/** A prompt that resolved to something chant can run. */
+export type ChantCommand = {
+    /** `chant run <op>` — the path that goes through the op runtime provider. */
+    kind: "op-run";
+    op: string;
+    args: ParsedArgs;
+    argv: string[];
+} | {
+    /** Any other chant verb — run through its own registry handler. */
+    kind: "verb";
+    name: string;
+    def: CommandDef;
+    compound: boolean;
+    args: ParsedArgs;
+    argv: string[];
+};
+/** Either a command, or the reason the prompt is not one. */
+export type CommandLineParse = {
+    ok: true;
+    command: ChantCommand;
+} | {
+    ok: false;
+    message: string;
+    hint: string;
+};
+/**
+ * Parse one prompt into a runnable chant command, or refuse it.
+ *
+ * Core's registry and argv parser are imported here rather than at module
+ * load: nothing about declaring the fountain lexicon should pull in every CLI
+ * handler, and only a live `chant acp` turn ever reaches this.
+ */
+export declare function parseChantCommandLine(text: string): Promise<CommandLineParse>;
+//# sourceMappingURL=command-line.d.ts.map

package/dist/acp/command-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-line.d.ts","sourceRoot":"","sources":["../../src/acp/command-line.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAsC/C;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GACpB;IACE,6EAA6E;IAC7E,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GACD;IACE,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,UAAU,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEN,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4DnF"}

package/dist/acp/host.d.ts

@@ -0,0 +1,63 @@
+/**
+ * What a turn needs from chant, stated once (#2125).
+ *
+ * The ACP server owns the protocol — sessions, updates, stop reasons — and
+ * nothing else. Everything it does *to a project* goes through this seam:
+ * finding an Op, starting it on a runtime provider, running any other chant
+ * verb, and recording a gate resolution. The conformance test drives the
+ * protocol through a stub host, so the tool-call ordering, the cancel path and
+ * the gated reply are tested without a checkout, a git branch or a real Op.
+ *
+ * The real implementation is `createChantHost`, and it is deliberately thin:
+ * `createLocalOpRuntime` from core is the provider (#2121), `discoverOps` is
+ * the lookup, and a verb runs through core's own registry handler rather than
+ * a reimplementation of it. Nothing here shells out — a prompt is parsed and
+ * dispatched in this process, so there is no line for a shell to interpret.
+ */
+import type { OpConfig } from "@intentius/chant/op/types";
+import type { OpRunHandle, OpRunStartOptions } from "@intentius/chant/op/runtime";
+import type { ChantCommand } from "./command-line.js";
+/**
+ * What one `*.op.ts` scan found.
+ *
+ * `errors` is carried rather than dropped because the failure mode it names is
+ * indistinguishable from the innocent one: an Op file that will not import
+ * reports as "no such Op", and a person reading that in a thread has been told
+ * the wrong thing. `chant run` prints these as warnings; so does a turn.
+ */
+export interface OpLookup {
+    /** The Op the prompt named, when the scan found it. */
+    config?: OpConfig;
+    /** Every Op name the scan did find, for the "not declared" reply's hint. */
+    names: string[];
+    /** Files the scan could not read as an Op. */
+    errors: string[];
+}
+/** The project-facing half of a turn. */
+export interface ChantHost {
+    /** Where chant runs — the session's `cwd`. */
+    readonly cwd: string;
+    /** Scan the project for Ops and pick out the one this name declares. */
+    findOp(name: string): Promise<OpLookup>;
+    /** Start an Op on the resolved runtime provider. */
+    startOp(op: OpConfig, opts: OpRunStartOptions): Promise<OpRunHandle>;
+    /** Run a non-`run` chant verb. Returns its exit code; output goes to the process writers. */
+    runVerb(command: Extract<ChantCommand, {
+        kind: "verb";
+    }>, signal: AbortSignal): Promise<number>;
+    /** Record a gate resolution, the way `chant approve` does (durable-request resume). */
+    resolveGate(op: string, gate: string, resolvedBy: string): Promise<void>;
+}
+/** How the real host identifies itself on a gate resolution it writes. */
+export declare const ACP_APPROVER = "chant-acp";
+/**
+ * The real host, bound to one session's working directory.
+ *
+ * Core's machinery reads the project from `process.cwd()`, so a turn changes
+ * into `cwd` for its duration (see ./turn.ts) rather than threading a path
+ * through every call — which is also why turns are serialized. Every import
+ * below is dynamic: declaring the fountain lexicon must not pull core's CLI
+ * handlers into a `chant build`.
+ */
+export declare function createChantHost(cwd: string): ChantHost;
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/acp/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,oDAAoD;IACpD,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACrE,6FAA6F;IAC7F,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChG,uFAAuF;IACvF,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED,0EAA0E;AAC1E,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAuCtD"}

package/dist/acp/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `chant acp` — the CLI mount for the ACP server (#2125).
+ *
+ * A command group with a `defaultVerb`, so the bare `chant acp` an editor or a
+ * fountain Agent spawns (`runtime_command: "chant acp"`) reaches `serve`
+ * without the client having to know chant's verb grammar. `chant acp serve`
+ * is the same thing spelled out.
+ *
+ * The server itself is behind a dynamic import: mounting the group happens
+ * every time a plugin loads, and nothing about `chant build` should pay for a
+ * JSON-RPC peer it will never open.
+ */
+import type { CommandGroup } from "@intentius/chant/cli/command-group";
+/** The verb group `chant acp` mounts. */
+export declare function acpCommandGroup(): CommandGroup;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/acp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,oCAAoC,CAAC;AAK5F,yCAAyC;AACzC,wBAAgB,eAAe,IAAI,YAAY,CAa9C"}

package/dist/acp/jsonrpc.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Newline-delimited JSON-RPC 2.0, both directions (#2125).
+ *
+ * ACP frames one JSON value per line. That is the whole transport, which is
+ * why this is ~150 lines of local code instead of a dependency: an agent that
+ * speaks the protocol needs a line reader, a writer that serializes its two
+ * writers, and a table of outbound requests waiting on answers.
+ *
+ * The peer is stream-agnostic on purpose. `chant acp` hands it the process's
+ * stdin and stdout; the conformance test hands it a pair of in-memory pipes
+ * and drives the client side in the same process, so the test exercises the
+ * real framing rather than a mock of it.
+ */
+import type { Readable, Writable } from "node:stream";
+/** The four JSON-RPC message kinds, told apart by which fields are present. */
+export interface JsonRpcMessage {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** An error a handler wants reported with a specific JSON-RPC code. */
+export declare class JsonRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+/** What the peer dispatches incoming traffic to. */
+export interface JsonRpcHandler {
+    /** Answer a request. The returned value is encoded as `result`. */
+    request(method: string, params: unknown): Promise<unknown>;
+    /** Handle a notification. JSON-RPC forbids a reply, so a rejection is dropped. */
+    notify(method: string, params: unknown): void;
+}
+/** A line-delimited byte channel, so the peer never names a stream type. */
+export interface LineTransport {
+    send(line: string): void;
+    onLine(cb: (line: string) => void): void;
+    onClose(cb: () => void): void;
+    close(): void;
+}
+/**
+ * A transport over a pair of Node streams — stdin and stdout, for `chant acp`.
+ *
+ * The writer is bound here, at construction, and that is load-bearing rather
+ * than tidy. A turn replaces `process.stdout.write` to stream a command's
+ * output (../acp/output.ts); if this looked the method up per call it would
+ * find the interceptor, every protocol line the turn emits would come back as
+ * another message chunk to emit, and the first notification sent inside a turn
+ * would recurse until V8 refused to grow the string. Binding once means the
+ * protocol always reaches the real stdout.
+ */
+export declare function streamTransport(input: Readable, output: Writable): LineTransport;
+/** An in-memory transport pair — one end for each side of a connection. */
+export declare function memoryTransportPair(): [LineTransport, LineTransport];
+/**
+ * One connection, serving a handler and able to originate requests of its own.
+ *
+ * The agent has two writers — request responses, and the `session/update`
+ * notifications a turn emits while a response is still pending. `send` is the
+ * single funnel for both, so two interleaved writes can never produce one
+ * unparseable line.
+ */
+export declare class JsonRpcPeer {
+    private readonly transport;
+    private readonly handler;
+    private nextId;
+    private readonly pending;
+    private closed;
+    constructor(transport: LineTransport, handler: JsonRpcHandler);
+    /** Send a notification. Fire and forget, by definition. */
+    notify(method: string, params: unknown): void;
+    /** Send a request and resolve with its `result`, or reject with its `error`. */
+    request(method: string, params: unknown): Promise<unknown>;
+    /** Stop serving and fail every outbound request still waiting. */
+    close(): void;
+    private shutdown;
+    private write;
+    private receive;
+}
+//# sourceMappingURL=jsonrpc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../../src/acp/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3D;AAED,uEAAuE;AACvE,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO;gBAFd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,OAAO,YAAA;CAK1B;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,kFAAkF;IAClF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/C;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACzC,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAG,aAAa,CAkChF;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CA8BpE;AAED;;;;;;;GAOG;AACH,qBAAa,WAAW;IASpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IACJ,OAAO,CAAC,MAAM,CAAS;gBAGJ,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,cAAc;IAM1C,2DAA2D;IAC3D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAI7C,gFAAgF;IAChF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1D,kEAAkE;IAClE,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,KAAK;YAKC,OAAO;CA8CtB"}

package/dist/acp/output.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Capturing what a chant command prints, so a turn can stream it (#2125).
+ *
+ * chant's own handlers and its activities print through `console.log` /
+ * `console.error`, which means the process's stdout and stderr are where a
+ * step's output actually appears — there is no per-step output channel on the
+ * executor to subscribe to instead. So a turn borrows both writers for its
+ * duration and forwards every chunk as an `agent_message_chunk`.
+ *
+ * Two consequences worth stating rather than discovering:
+ *
+ * - The `chant acp` process writes the protocol on stdout, so a turn MUST
+ *   hold this capture over everything it runs. A stray `console.log` reaching
+ *   the real stdout mid-turn is an unparseable line to the client.
+ * - The capture is process-wide, so turns are serialized (see
+ *   ./server.ts). One stdio connection running one command at a time is the
+ *   honest shape anyway.
+ *
+ * Redaction is deliberately absent. A step's output is the environment's
+ * output, and fountain redacts a thread's secrets on the way in — the
+ * documented division of labour in ../skills/chant-fountain.md. This server
+ * never reads or prints the environment it inherits.
+ */
+/** Where a captured chunk came from. */
+export type OutputStream = "stdout" | "stderr";
+/** Run `fn` with both process writers forwarded to `onChunk`, and restore them after. */
+export declare function withCapturedOutput<T>(onChunk: (text: string, stream: OutputStream) => void, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=output.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/acp/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/C,yFAAyF;AACzF,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,EACrD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CA2BZ"}

package/dist/acp/protocol.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The Agent Client Protocol wire shapes `chant acp` speaks (#2125).
+ *
+ * ACP (<https://agentclientprotocol.com>) is JSON-RPC 2.0 between a *client*
+ * — an editor, or fountain — and an *agent*. chant is the agent half here: it
+ * is spawned, it answers `initialize`, it opens sessions, and every prompt it
+ * receives is one chant command line.
+ *
+ * These are hand-written rather than pulled from a package on purpose. The
+ * subset an agent has to speak is small enough to state in one file, and a
+ * dependency for it would be a dependency in every project that declares the
+ * fountain lexicon. Field names match what fountain's own ACP client sends
+ * and expects (fountain ADR 0014, `cli/internal/acp`), which is the same
+ * vocabulary the specification defines — a client of ours that is not
+ * fountain sees nothing fountain-specific.
+ */
+/** The ACP major version this agent speaks. */
+export declare const ACP_PROTOCOL_VERSION = 1;
+/** JSON-RPC 2.0 error codes, plus the one ACP adds. */
+export declare const JSONRPC_PARSE_ERROR = -32700;
+export declare const JSONRPC_INVALID_REQUEST = -32600;
+export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
+export declare const JSONRPC_INVALID_PARAMS = -32602;
+export declare const JSONRPC_INTERNAL_ERROR = -32603;
+/**
+ * How a turn ended.
+ *
+ * `end_turn`, `cancelled` and `refusal` are the specification's.
+ *
+ * `waiting` is not: it is what `--durable-requests` returns for a run that
+ * stopped at a gate whose `session/request_permission` will be answered after
+ * this turn is over (BinaryBourbon/fountain#1635). Until that ships, no client
+ * can answer such a request within the turn, and reporting `end_turn` for a
+ * run that has not finished would be a lie a client renders as success. The
+ * flag is off by default for exactly this reason — see ../acp/server.ts.
+ */
+export type StopReason = "end_turn" | "cancelled" | "refusal" | "waiting";
+/** A tool call's lifecycle, as a client renders it. */
+export type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+/** One text block in a prompt or an update. */
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+/** `initialize` params. */
+export interface InitializeParams {
+    protocolVersion?: number;
+    clientCapabilities?: unknown;
+}
+/** `initialize` result. */
+export interface InitializeResult {
+    protocolVersion: number;
+    agentInfo: {
+        name: string;
+        title: string;
+        version: string;
+    };
+    agentCapabilities: {
+        loadSession: boolean;
+        promptCapabilities: {
+            image: boolean;
+            audio: boolean;
+            embeddedContext: boolean;
+        };
+    };
+    authMethods: unknown[];
+}
+/** `session/new` params. `mcpServers` is accepted and ignored — see the server's module doc. */
+export interface NewSessionParams {
+    cwd?: string;
+    mcpServers?: unknown[];
+    _meta?: Record<string, unknown>;
+}
+/** `session/new` result. */
+export interface NewSessionResult {
+    sessionId: string;
+}
+/**
+ * The out-of-band bag a client attaches to `session/prompt` to resume a
+ * durable permission request (#2125). ACP's `_meta` is the extension point
+ * fountain already uses for its own `channelId`, so a resume needs no method
+ * of its own and a client that does not do durable requests never sends it.
+ */
+export interface ChantPromptMeta {
+    /** Answers a `session/request_permission` this agent sent in an earlier turn. */
+    permission?: {
+        requestId: string;
+        optionId: string;
+    };
+}
+/** `session/prompt` params. */
+export interface PromptParams {
+    sessionId: string;
+    prompt: Array<TextContent | {
+        type: string;
+        [k: string]: unknown;
+    }>;
+    _meta?: {
+        chant?: ChantPromptMeta;
+        [k: string]: unknown;
+    };
+}
+/** `session/prompt` result. */
+export interface PromptResult {
+    stopReason: StopReason;
+}
+/** `session/cancel` params. A notification: the pending prompt is what answers. */
+export interface CancelParams {
+    sessionId: string;
+}
+/** The `session/update` variants this agent emits. */
+export type SessionUpdate = {
+    sessionUpdate: "agent_message_chunk";
+    content: TextContent;
+} | {
+    sessionUpdate: "tool_call";
+    toolCallId: string;
+    title: string;
+    kind: "execute";
+    status: ToolCallStatus;
+    rawInput?: Record<string, unknown>;
+} | {
+    sessionUpdate: "tool_call_update";
+    toolCallId: string;
+    status: ToolCallStatus;
+    content?: TextContent[];
+    rawOutput?: Record<string, unknown>;
+};
+/** `session/update` notification params. */
+export interface SessionNotification {
+    sessionId: string;
+    update: SessionUpdate;
+}
+/** One choice offered on a `session/request_permission`. */
+export interface PermissionOption {
+    optionId: string;
+    name: string;
+    kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+}
+/** `session/request_permission` params. */
+export interface RequestPermissionParams {
+    sessionId: string;
+    toolCall: {
+        toolCallId: string;
+        title: string;
+        kind: "execute";
+    };
+    options: PermissionOption[];
+    _meta?: Record<string, unknown>;
+}
+/** `session/request_permission` result. */
+export interface RequestPermissionResult {
+    outcome: {
+        outcome: "selected";
+        optionId: string;
+    } | {
+        outcome: "cancelled";
+    };
+}
+//# sourceMappingURL=protocol.d.ts.map

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

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

package/dist/acp/serve.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `chant acp` on the process's own stdio (#2125).
+ *
+ * Split from ./index.ts so mounting the command group costs nothing: this
+ * module is imported only once a client has actually spawned the agent.
+ *
+ * stdout is the protocol. Nothing else may write to it for the life of the
+ * process — every turn holds the output capture (./output.ts) precisely so a
+ * command's `console.log` cannot land between two JSON-RPC lines.
+ */
+/** Serve until the client closes stdin, which is how it says the connection is over. */
+export declare function serveAcpOverStdio(opts?: {
+    durableRequests?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/acp/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,wFAAwF;AACxF,wBAAsB,iBAAiB,CAAC,IAAI,GAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa/F"}

package/dist/acp/server.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `chant acp` — chant as an Agent Client Protocol agent (#2125, epic #2115).
+ *
+ * An editor or fountain spawns this process, speaks JSON-RPC 2.0 over stdio,
+ * and gets `session/update` notifications back. Every prompt is one chant
+ * command line, so a fountain thread of turns reads as an environment's shell
+ * history, and a run's steps arrive as tool calls a client already knows how
+ * to render.
+ *
+ * It is fountain-agnostic by construction. Nothing here imports the fountain
+ * API, a fountain type, or a fountain URL; it lives in this lexicon because
+ * fountain is its first host (epic #2115's steward runs `runtime: "acp"`,
+ * `runtime_command: "chant acp"`), and any ACP client can drive it unchanged.
+ *
+ * Three deliberate limits:
+ *
+ * - **Turns are serialized.** A turn borrows the process writers to stream a
+ *   command's output (./output.ts) and changes into the session's `cwd`
+ *   (./turn.ts). Both are process-wide, so two turns at once would interleave.
+ *   One stdio connection running one command at a time is the honest shape.
+ * - **`mcpServers` from `session/new` is ignored.** chant's tools are its own
+ *   verbs; there is nothing here for an MCP server to extend.
+ * - **The server never reads or prints the environment it inherits.** A step's
+ *   output is streamed verbatim, secrets included, because redaction belongs
+ *   to the thread that stores it — fountain redacts on the way in (see
+ *   ../skills/chant-fountain.md).
+ */
+import { JsonRpcPeer, type JsonRpcHandler, type LineTransport } from "./jsonrpc.js";
+import { type ChantHost } from "./host.js";
+/** How `chant acp` is configured, and where a test substitutes its own project. */
+export interface AcpServerOptions {
+    /**
+     * Behind BinaryBourbon/fountain#1635: carry a gate to the client as a
+     * `session/request_permission` and end the turn `waiting`, instead of
+     * replying with the approve line and ending it. Default off, because no
+     * client can answer a request that outlives a turn until #1635 ships.
+     */
+    durableRequests?: boolean;
+    /** Version reported as `agentInfo`. */
+    version?: string;
+    /** Builds the project-facing half of a session. Substituted by the conformance test. */
+    createHost?: (cwd: string) => ChantHost;
+    /** Mints permission request ids. Injected so a test can pin them. */
+    newRequestId?: () => string;
+}
+export declare class AcpServer implements JsonRpcHandler {
+    private peer;
+    private readonly sessions;
+    private readonly durableRequests;
+    private readonly version;
+    private readonly createHost;
+    private readonly newRequestId;
+    /** Serializes turns — see the module doc. */
+    private queue;
+    constructor(opts?: AcpServerOptions);
+    /** Serve one connection until it closes. */
+    connect(transport: LineTransport): JsonRpcPeer;
+    request(method: string, params: unknown): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    private enqueue;
+    private initialize;
+    private newSession;
+    private prompt;
+    /**
+     * Answer a `session/request_permission` this agent sent in an earlier turn.
+     *
+     * Allowing writes the gate resolution the way `chant approve` does — the
+     * fact is chant's, not the protocol's — and re-runs the command line that
+     * hit the gate, which now walks through it.
+     */
+    private resume;
+    private runCommandLine;
+    /** The client-facing half of a turn, bound to one session. */
+    private sinkFor;
+}
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/acp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAEL,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AAoBnB,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGvE,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IACxC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAgBD,qBAAa,SAAU,YAAW,cAAc;IAC9C,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,6CAA6C;IAC7C,OAAO,CAAC,KAAK,CAAuC;gBAExC,IAAI,GAAE,gBAAqB;IAOvC,4CAA4C;IAC5C,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,WAAW;IAKxC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAahE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAU7C,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,UAAU;YAYJ,MAAM;IAcpB;;;;;;OAMG;YACW,MAAM;YAuCN,cAAc;IAiC5B,8DAA8D;IAC9D,OAAO,CAAC,OAAO;CA0DhB"}