@intentius/chant-lexicon-fountain 0.102.0 → 0.104.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { observeResourcesDeepFountain } from "./deep-observe.js";
 export type { FountainDeepObserveOptions } from "./deep-observe.js";
 export { fountainDeepNormalizationHooks, FOUNTAIN_SERVER_FIELDS, FOUNTAIN_DEFAULTS, } from "./deep-observe-hooks.js";
 export * from "./generated/index.js";
-export { fountainApply, fountainRun, DEFAULT_FOUNTAIN_BASE_URL } from "./op/activities/index.js";
+export { fountainApply, fountainRun, fountainPrompt, DEFAULT_FOUNTAIN_BASE_URL } from "./op/activities/index.js";
 export type { FountainApplyArgs, FountainApplySummary, FountainRunArgs, FountainRunResult } from "./op/activities/index.js";
 export { fountainConfigSchema, resolveProfile } from "./config.js";
 export type { FountainConfig, FountainProfile } from "./config.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAInH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAIhE,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG5F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC7G,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACzG,OAAO,EACL,GAAG,EACH,qBAAqB,EACrB,+BAA+B,EAC/B,mCAAmC,EACnC,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIxI,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxG,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAInH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAIhE,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG5F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC7G,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACzG,OAAO,EACL,GAAG,EACH,qBAAqB,EACrB,+BAA+B,EAC/B,mCAAmC,EACnC,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIxI,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "6a31ea7fecb3b65dfff50c618e0c913128caf2a9ffc6ae2c88e302faffc527bf",
+    "manifest.json": "76b78ea255b90a278d3669a41c53507ddc92b2489a7b2a2c36b2bca47ee41561",
     "meta.json": "3301437a2a56eaf1a5cc8f6eabb18a40767f916e09701b2d9bf20aba4066738c",
     "types/index.d.ts": "cf6b634fe0a8e9e96f1d9d07e3df53838def2683dc93dbe3c7fd971c6d3908ae",
     "rules/ftn001-no-secret-literals.ts": "a417b194cd7039911cca9a0f14c49b042dfa6b1ee48517f7c2e22b16590a8599",
@@ -21,7 +21,7 @@
     "skills/chant-fountain.md": "906a312756a02c88de634915f63ab4dfe1b1078ff4d8cfb4b6dc97eec14bc237",
     "skills/chant-fountain-secrets.md": "40aa847d62547581bebdde630b54796c4e1cbf498869392e0d396d96a75c0ab6",
     "skills/chant-fountain-ops.md": "4e72f0a0c7477a9e98f85ea45e49ba69e8a699f9c13ba0f0cf1cb20a88151373",
-    "skills/chant-fountain-locked-sandboxes.md": "14def4c68b13c2bd561f75819b188968cec85073a5dd8b59e91708e1af26daae"
+    "skills/chant-fountain-locked-sandboxes.md": "48f4840a891e6b1cc7b5ac3319aebaec8c4e934f452370e55d60cb02a05812ae"
   },
-  "composite": "6ddf244e344acbe1d2f46049ba25cd65b6a8e2c115a069ab0a9457cf3aeb5af9"
+  "composite": "6b479490227e45d1639ae76d30a4915eba2b4dcfd062e766f92b0c01428b47e7"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fountain",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Fountain",
   "specVersion": "v0.21.0"

package/dist/op/activities/fountain-prompt.d.ts

@@ -0,0 +1,83 @@
+/**
+ * fountainPrompt: add a turn to a conversation that already exists, and
+ * follow that turn to its end (#3356).
+ *
+ * `fountainRun` starts a conversation and waits out its first turn. This is
+ * the next turn on the same conversation: fountain's
+ * `POST /api/conversations/{id}/prompts`, which queues a turn on the same
+ * runtime session (fountain wakes the conversation, provisioning a fresh
+ * machine that resumes the session, when its server has gone). The turn is
+ * found by the `client_request_id` this sends with the prompt, and polled on
+ * `GET .../turns` until it is `completed`, `failed` or `interrupted`.
+ *
+ * What fountain v0.21.0 can and cannot do here, which decides the arguments:
+ *
+ * - A conversation that is `terminated` takes no more turns: the prompts route
+ *   answers 410. `fountainRun` terminates an ephemeral agent's conversation at
+ *   its deadline by default, so a caller that wants a later turn runs the first
+ *   one with `terminate: "never"` (a persistent agent's default) and ends the
+ *   conversation itself, or with this op's `terminate`, after the last turn.
+ * - A turn has no tool allowlist of its own. The prompts route takes only the
+ *   prompt, images and `client_request_id`; the tools a conversation may use are
+ *   its agent's `permission_policy`, narrowed once at launch, and nothing on the
+ *   API narrows them for one turn. So this op takes no `tools`: the narrowing
+ *   has to be on the agent, or on the launch.
+ * - A turn has no cap on its agent loop. The cap here is time: past `timeoutMs`
+ *   the turn is interrupted (`POST .../interrupt`), which ends the turn and
+ *   leaves the conversation up.
+ *
+ * Under `chant run` the executor calls this as `fountainPrompt(args, signal)`.
+ * When the signal fires, polling stops, the turn is interrupted, the
+ * `terminate` policy is applied as at the deadline, and the step fails with
+ * the abort's reason.
+ */
+import { type FountainHttp, type FountainConnectionDeps } from "./fountain-apply.js";
+import type { TerminatePolicy } from "./fountain-run.js";
+export interface FountainPromptArgs {
+    /** The conversation's id, as `fountainRun` returns it in `conversationId`. */
+    conversation: string;
+    /** The turn's prompt. Must carry words. */
+    prompt: string;
+    /**
+     * fountain's `client_request_id`: the name the turn is found by. Defaults
+     * to `chant-<uuid>`. Make it unique within the conversation; fountain does
+     * not deduplicate on it.
+     */
+    clientRequestId?: string;
+    endpoint?: string;
+    token?: string;
+    /** Named `fountain.profiles` entry to resolve endpoint/token from, as for `fountainRun`. */
+    profile?: string;
+    /** Project root `chant.config.ts` is read from. Default: process.cwd(). */
+    cwd?: string;
+    /** The turn's cap: past this the turn is interrupted. Default 10 min. */
+    timeoutMs?: number;
+    /** Poll interval. Default 5s. */
+    pollMs?: number;
+    /**
+     * What happens to the conversation when the wait ends: `never` (the
+     * default) leaves it up for another turn, `on-deadline` terminates it only
+     * when the turn had to be interrupted, `always` terminates it either way.
+     */
+    terminate?: TerminatePolicy;
+    /** Injectable sleep for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface FountainPromptResult {
+    conversationId: string;
+    /** The `client_request_id` the turn was sent and found by. */
+    clientRequestId: string;
+    /** The turn's id and number, once fountain listed the turn. */
+    turnId?: string;
+    turnNumber?: number;
+    /** The turn's outcome: `completed`, `failed` or `interrupted`. */
+    status: string;
+    /** True when the turn ran past `timeoutMs` and was interrupted. */
+    interruptedByDeadline: boolean;
+    /** fountain's `limit_reason`: a service limit that ended the turn, which makes even a `completed` turn incomplete. */
+    limitReason?: string;
+    /** True when the conversation was terminated after the turn. */
+    terminated: boolean;
+}
+export declare function fountainPrompt(args: FountainPromptArgs, signal?: AbortSignal, http?: FountainHttp, deps?: FountainConnectionDeps): Promise<FountainPromptResult>;
+//# sourceMappingURL=fountain-prompt.d.ts.map

package/dist/op/activities/fountain-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fountain-prompt.d.ts","sourceRoot":"","sources":["../../../src/op/activities/fountain-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKtD,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,kCAAkC;IAClC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,sHAAsH;IACtH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;CACrB;AAuCD,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,EACxB,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,CAAC,EAAE,sBAAsB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CA2D/B"}

package/dist/op/activities/index.d.ts

@@ -2,10 +2,13 @@
  * fountain Op activities — resolved by the core activity registry when a
  * project's `chant.config.ts` lists the `fountain` lexicon. Contributes
  * the native applier (`fountainApply` — direct REST against fountain's
- * API, no CLI, no state file) and the conversation runner (`fountainRun`).
+ * API, no CLI, no state file), the conversation runner (`fountainRun`) and
+ * the next turn on a conversation (`fountainPrompt`, #3356).
  */
 export { fountainApply, resolveEndpoint, resolveToken, resolveConnection, parseManifest, toApplyPayload, isChantOwned, defaultFountainHttp, DEFAULT_FOUNTAIN_BASE_URL, OWNERSHIP_KEY, OWNERSHIP_VALUE, } from "./fountain-apply.js";
 export type { FountainApplyArgs, FountainApplySummary, ManifestResource, FountainHttp, FountainConnectionDeps, } from "./fountain-apply.js";
 export { fountainRun, resolveAgent, resolveAgentId, TERMINAL_STATUSES, PERSISTENT_DONE_STATUSES, } from "./fountain-run.js";
 export type { FountainRunArgs, FountainRunResult, ResolvedAgent, TerminatePolicy } from "./fountain-run.js";
+export { fountainPrompt } from "./fountain-prompt.js";
+export type { FountainPromptArgs, FountainPromptResult } from "./fountain-prompt.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEzG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/skills/chant-fountain-locked-sandboxes.md

@@ -31,4 +31,4 @@ The environment's config is the enforcement boundary, so watch it: `chant lifecy
 
 ## Running conversations
 
-Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), and waits for the turn to end. What "end" means, and what happens to the machine, follows the agent's `sandbox_mode`: an `ephemeral` agent's conversation is polled for a terminal status and terminated on deadline, same as before; a `persistent` agent's (a `Steward` or `Box`) conversation settles on `idle` once its turn ends — machine still up for the next turn — so `fountainRun` reads the turn back and returns its outcome (`completed | failed | interrupted`) without terminating anything, by default. Pass `terminate: "on-deadline" | "always"` to opt a persistent agent's run back into ending the machine. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.
+Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), and waits for the turn to end. What "end" means, and what happens to the machine, follows the agent's `sandbox_mode`: an `ephemeral` agent's conversation is polled for a terminal status and terminated on deadline, same as before; a `persistent` agent's (a `Steward` or `Box`) conversation settles on `idle` once its turn ends — machine still up for the next turn — so `fountainRun` reads the turn back and returns its outcome (`completed | failed | interrupted`) without terminating anything, by default. Pass `terminate: "on-deadline" | "always"` to opt a persistent agent's run back into ending the machine. To add a turn to a conversation that already exists, use `fountainPrompt` with the conversation's id: it sends the prompt on the same session and waits for that turn, interrupting it at `timeoutMs`. It cannot reach a terminated conversation (fountain answers 410), so run the earlier turn with `terminate: "never"`, and it cannot narrow tools for one turn: that is the agent's `permission_policy`, set at launch. Interrupts and permission answers on their own are fountain's own conversations API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fountain",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "type": "module",
   "description": "Fountain lexicon for chant — sandboxed agent environments, vaults, and agents as typed estate",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
     "bundle": "tsx src/package-cli.ts"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.102.0",
+    "@intentius/chant": "^0.104.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },

package/src/coverage.ts

@@ -35,7 +35,7 @@ import { parseFountainOpenAPI, fountainShortName, MODELED_REQUEST_SCHEMAS } from
 export const EXCLUDED_KINDS: Record<string, string> = {
   // Runs, turns, and the envelope around them.
   ConversationCreateRequest: "conversations are runs, not declarables — started by the fountainRun op",
-  PromptRequest: "turn-level input inside a conversation run",
+  PromptRequest: "turn-level input inside a conversation run — sent by the fountainPrompt op",
   PermissionAnswerRequest: "a human's answer to one tool card mid-run — an event on a conversation, not estate",
   TeamMessageRequest: "one turn addressed to a teammate — the run, not the seat",
   ConversationLabelsRequest:

package/src/index.ts

@@ -19,7 +19,7 @@ export * from "./generated/index";
 
 // Op activities — the native applier and conversation runner. Also
 // resolvable by name via loadActivities(["fountain"]).
-export { fountainApply, fountainRun, DEFAULT_FOUNTAIN_BASE_URL } from "./op/activities";
+export { fountainApply, fountainRun, fountainPrompt, DEFAULT_FOUNTAIN_BASE_URL } from "./op/activities";
 export type { FountainApplyArgs, FountainApplySummary, FountainRunArgs, FountainRunResult } from "./op/activities";
 
 // Config namespace (#2124) — `fountain.profiles` in chant.config.ts, and the

package/src/op/activities/fountain-prompt.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { fountainPrompt } from "./fountain-prompt";
+import type { FountainHttp } from "./fountain-apply";
+
+/** A conversation that takes one prompt and lists the turn it opens through `turns`, one reply per poll. */
+function conversation(opts: { promptStatus?: number; promptJson?: unknown; turns: Array<Array<Record<string, unknown>>> }) {
+  const calls: string[] = [];
+  const bodies: unknown[] = [];
+  let poll = 0;
+  let sentId: string | undefined;
+  const http: FountainHttp = async (method, path, body) => {
+    calls.push(`${method} ${path}`);
+    if (method === "POST" && path === "/api/conversations/conv-1/prompts") {
+      bodies.push(body);
+      sentId = (body as { client_request_id?: string }).client_request_id;
+      return { status: opts.promptStatus ?? 200, json: opts.promptJson ?? { status: "queued", client_request_id: sentId } };
+    }
+    if (method === "GET" && path === "/api/conversations/conv-1/turns") {
+      const page = opts.turns[Math.min(poll, opts.turns.length - 1)];
+      poll += 1;
+      return { status: 200, json: { data: page.map((t) => ({ client_request_id: sentId, ...t })) } };
+    }
+    if (method === "POST" && (path === "/api/conversations/conv-1/interrupt" || path === "/api/conversations/conv-1/terminate")) {
+      return { status: 200, json: null };
+    }
+    throw new Error(`unrouted: ${method} ${path}`);
+  };
+  return { http, calls, bodies };
+}
+
+const quick = { pollMs: 1, sleep: async () => {} };
+/** The build's own turn, which carries no client_request_id of ours. */
+const build = { id: "t-1", turn_number: 1, status: "completed", client_request_id: null };
+
+describe("fountainPrompt (#3356)", () => {
+  it("sends the prompt to the conversation, finds its turn by client_request_id, and returns the turn's outcome", async () => {
+    const { http, calls, bodies } = conversation({
+      turns: [[build], [build, { id: "t-2", turn_number: 2, status: "running" }], [build, { id: "t-2", turn_number: 2, status: "completed" }]],
+    });
+    const result = await fountainPrompt({ conversation: "conv-1", prompt: "debrief", clientRequestId: "debrief-W-012", ...quick }, undefined, http);
+    expect(bodies).toEqual([{ prompt: "debrief", client_request_id: "debrief-W-012" }]);
+    expect(result).toEqual({
+      conversationId: "conv-1",
+      clientRequestId: "debrief-W-012",
+      turnId: "t-2",
+      turnNumber: 2,
+      status: "completed",
+      interruptedByDeadline: false,
+      terminated: false,
+    });
+    expect(calls.filter((c) => c.endsWith("/terminate") || c.endsWith("/interrupt"))).toEqual([]);
+  });
+
+  it("names its own client_request_id when given none, and reports a service limit that ended the turn", async () => {
+    const { http, bodies } = conversation({ turns: [[{ id: "t-2", turn_number: 2, status: "completed", limit_reason: "turn_deadline" }]] });
+    const result = await fountainPrompt({ conversation: "conv-1", prompt: "debrief", ...quick }, undefined, http);
+    const sent = (bodies[0] as { client_request_id: string }).client_request_id;
+    expect(sent).toMatch(/^chant-[0-9a-f-]{36}$/);
+    expect(result).toMatchObject({ clientRequestId: sent, status: "completed", limitReason: "turn_deadline" });
+  });
+
+  it("caps the turn by time: past timeoutMs it interrupts the turn and leaves the conversation up", async () => {
+    const running = [{ id: "t-2", turn_number: 2, status: "running" }];
+    // Polled at 0, 4 and 8 ms, running each time; read once more after the interrupt.
+    const { http, calls } = conversation({ turns: [running, running, running, [{ id: "t-2", turn_number: 2, status: "interrupted" }]] });
+    let now = 0;
+    const realNow = Date.now;
+    Date.now = () => now;
+    try {
+      const result = await fountainPrompt({ conversation: "conv-1", prompt: "debrief", timeoutMs: 10, pollMs: 4, sleep: async (ms) => void (now += ms) }, undefined, http);
+      expect(result).toMatchObject({ status: "interrupted", interruptedByDeadline: true, terminated: false, turnId: "t-2" });
+    } finally {
+      Date.now = realNow;
+    }
+    expect(calls).toContain("POST /api/conversations/conv-1/interrupt");
+    expect(calls).not.toContain("POST /api/conversations/conv-1/terminate");
+  });
+
+  it("terminates the conversation after the turn when asked, and only on the deadline with on-deadline", async () => {
+    const always = conversation({ turns: [[{ id: "t-2", turn_number: 2, status: "completed" }]] });
+    expect(await fountainPrompt({ conversation: "conv-1", prompt: "debrief", terminate: "always", ...quick }, undefined, always.http)).toMatchObject({ terminated: true });
+    expect(always.calls.at(-1)).toBe("POST /api/conversations/conv-1/terminate");
+    const onDeadline = conversation({ turns: [[{ id: "t-2", turn_number: 2, status: "failed" }]] });
+    expect(await fountainPrompt({ conversation: "conv-1", prompt: "debrief", terminate: "on-deadline", ...quick }, undefined, onDeadline.http)).toMatchObject({ status: "failed", terminated: false });
+  });
+
+  it("says precisely why fountain refused the turn: a terminated conversation, a busy one, an unknown one", async () => {
+    const terminated = conversation({ promptStatus: 410, promptJson: { error: "conversation_terminal" }, turns: [[]] });
+    await expect(fountainPrompt({ conversation: "conv-1", prompt: "debrief", ...quick }, undefined, terminated.http)).rejects.toThrow(
+      /conv-1 is terminated, and fountain adds no turn to a terminated conversation/,
+    );
+    const busy = conversation({ promptStatus: 400, turns: [[]] });
+    await expect(fountainPrompt({ conversation: "conv-1", prompt: "debrief", ...quick }, undefined, busy.http)).rejects.toThrow(/busy: a turn is running/);
+    const missing = conversation({ promptStatus: 404, turns: [[]] });
+    await expect(fountainPrompt({ conversation: "conv-1", prompt: "debrief", ...quick }, undefined, missing.http)).rejects.toThrow(/no conversation conv-1/);
+  });
+
+  it("refuses a missing conversation id or an empty prompt before calling fountain", async () => {
+    const http: FountainHttp = async () => {
+      throw new Error("should not be called");
+    };
+    await expect(fountainPrompt({ conversation: "", prompt: "hi" }, undefined, http)).rejects.toThrow(/conversation's id/);
+    await expect(fountainPrompt({ conversation: "conv-1", prompt: "  " }, undefined, http)).rejects.toThrow(/prompt with words/);
+  });
+
+  it("on abort it interrupts the turn, applies the terminate policy, and fails with the abort's reason", async () => {
+    const { http, calls } = conversation({ turns: [[{ id: "t-2", turn_number: 2, status: "running" }]] });
+    const abort = new AbortController();
+    const run = fountainPrompt(
+      { conversation: "conv-1", prompt: "debrief", terminate: "on-deadline", pollMs: 1, sleep: async () => abort.abort(new Error("lease-lost")) },
+      abort.signal,
+      http,
+    );
+    await expect(run).rejects.toThrow(/lease-lost/);
+    expect(calls.slice(-2)).toEqual(["POST /api/conversations/conv-1/interrupt", "POST /api/conversations/conv-1/terminate"]);
+  });
+});

package/src/op/activities/fountain-prompt.ts

@@ -0,0 +1,197 @@
+/**
+ * fountainPrompt: add a turn to a conversation that already exists, and
+ * follow that turn to its end (#3356).
+ *
+ * `fountainRun` starts a conversation and waits out its first turn. This is
+ * the next turn on the same conversation: fountain's
+ * `POST /api/conversations/{id}/prompts`, which queues a turn on the same
+ * runtime session (fountain wakes the conversation, provisioning a fresh
+ * machine that resumes the session, when its server has gone). The turn is
+ * found by the `client_request_id` this sends with the prompt, and polled on
+ * `GET .../turns` until it is `completed`, `failed` or `interrupted`.
+ *
+ * What fountain v0.21.0 can and cannot do here, which decides the arguments:
+ *
+ * - A conversation that is `terminated` takes no more turns: the prompts route
+ *   answers 410. `fountainRun` terminates an ephemeral agent's conversation at
+ *   its deadline by default, so a caller that wants a later turn runs the first
+ *   one with `terminate: "never"` (a persistent agent's default) and ends the
+ *   conversation itself, or with this op's `terminate`, after the last turn.
+ * - A turn has no tool allowlist of its own. The prompts route takes only the
+ *   prompt, images and `client_request_id`; the tools a conversation may use are
+ *   its agent's `permission_policy`, narrowed once at launch, and nothing on the
+ *   API narrows them for one turn. So this op takes no `tools`: the narrowing
+ *   has to be on the agent, or on the launch.
+ * - A turn has no cap on its agent loop. The cap here is time: past `timeoutMs`
+ *   the turn is interrupted (`POST .../interrupt`), which ends the turn and
+ *   leaves the conversation up.
+ *
+ * Under `chant run` the executor calls this as `fountainPrompt(args, signal)`.
+ * When the signal fires, polling stops, the turn is interrupted, the
+ * `terminate` policy is applied as at the deadline, and the step fails with
+ * the abort's reason.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  abortable,
+  resolveConnection,
+  defaultFountainHttp,
+  type FountainHttp,
+  type FountainConnectionDeps,
+} from "./fountain-apply";
+import type { TerminatePolicy } from "./fountain-run";
+
+/** Turn statuses that mean the turn has ended: fountain's `end_turn`, an error, or an interrupt. */
+const ENDED_TURN_STATUSES = new Set(["completed", "failed", "interrupted"]);
+
+export interface FountainPromptArgs {
+  /** The conversation's id, as `fountainRun` returns it in `conversationId`. */
+  conversation: string;
+  /** The turn's prompt. Must carry words. */
+  prompt: string;
+  /**
+   * fountain's `client_request_id`: the name the turn is found by. Defaults
+   * to `chant-<uuid>`. Make it unique within the conversation; fountain does
+   * not deduplicate on it.
+   */
+  clientRequestId?: string;
+  endpoint?: string;
+  token?: string;
+  /** Named `fountain.profiles` entry to resolve endpoint/token from, as for `fountainRun`. */
+  profile?: string;
+  /** Project root `chant.config.ts` is read from. Default: process.cwd(). */
+  cwd?: string;
+  /** The turn's cap: past this the turn is interrupted. Default 10 min. */
+  timeoutMs?: number;
+  /** Poll interval. Default 5s. */
+  pollMs?: number;
+  /**
+   * What happens to the conversation when the wait ends: `never` (the
+   * default) leaves it up for another turn, `on-deadline` terminates it only
+   * when the turn had to be interrupted, `always` terminates it either way.
+   */
+  terminate?: TerminatePolicy;
+  /** Injectable sleep for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface FountainPromptResult {
+  conversationId: string;
+  /** The `client_request_id` the turn was sent and found by. */
+  clientRequestId: string;
+  /** The turn's id and number, once fountain listed the turn. */
+  turnId?: string;
+  turnNumber?: number;
+  /** The turn's outcome: `completed`, `failed` or `interrupted`. */
+  status: string;
+  /** True when the turn ran past `timeoutMs` and was interrupted. */
+  interruptedByDeadline: boolean;
+  /** fountain's `limit_reason`: a service limit that ended the turn, which makes even a `completed` turn incomplete. */
+  limitReason?: string;
+  /** True when the conversation was terminated after the turn. */
+  terminated: boolean;
+}
+
+interface TurnView {
+  id?: string;
+  turn_number?: number;
+  status?: string;
+  client_request_id?: string | null;
+  limit_reason?: string | null;
+}
+
+/** The latest turn opened by `clientRequestId`, or undefined. */
+async function turnOf(http: FountainHttp, conversationId: string, clientRequestId: string): Promise<TurnView | undefined> {
+  const { status, json } = await http("GET", `/api/conversations/${conversationId}/turns`);
+  if (status !== 200) return undefined;
+  const turns = ((json as { data?: TurnView[] })?.data ?? []).filter((t) => t.client_request_id === clientRequestId);
+  if (turns.length === 0) return undefined;
+  return turns.reduce((a, b) => ((b.turn_number ?? 0) > (a.turn_number ?? 0) ? b : a));
+}
+
+function refusal(conversationId: string, status: number, json: unknown): Error {
+  const detail = (json as { error?: unknown; errors?: unknown } | null)?.error ?? (json as { errors?: unknown } | null)?.errors;
+  const why = detail === undefined ? "" : `: ${typeof detail === "string" ? detail : JSON.stringify(detail)}`;
+  switch (status) {
+    case 410:
+      return new Error(
+        `fountainPrompt: conversation ${conversationId} is terminated, and fountain adds no turn to a terminated conversation. ` +
+          `Run the earlier turn with terminate: "never" and end the conversation after the last turn`,
+      );
+    case 400:
+      return new Error(`fountainPrompt: conversation ${conversationId} is busy: a turn is running (400)${why}`);
+    case 404:
+      return new Error(`fountainPrompt: no conversation ${conversationId} (404)`);
+    case 409:
+      return new Error(`fountainPrompt: conversation ${conversationId}'s sandbox is being reset or deleted (409)${why}`);
+    default:
+      return new Error(`fountainPrompt: the prompt was refused (${status})${why}`);
+  }
+}
+
+export async function fountainPrompt(
+  args: FountainPromptArgs,
+  signal?: AbortSignal,
+  http?: FountainHttp,
+  deps?: FountainConnectionDeps,
+): Promise<FountainPromptResult> {
+  if (typeof args?.conversation !== "string" || args.conversation === "") throw new Error("fountainPrompt: needs the conversation's id");
+  if (typeof args.prompt !== "string" || args.prompt.trim() === "") throw new Error("fountainPrompt: needs a prompt with words in it");
+  // `raw` reaches fountain after the signal has fired, for the interrupt and terminate.
+  let raw = http;
+  let client = http;
+  if (!raw) {
+    const { endpoint, token } = await resolveConnection(args, deps);
+    raw = defaultFountainHttp(endpoint, token);
+    client = defaultFountainHttp(endpoint, token, signal);
+  }
+  client = abortable(client!, signal);
+  const sleep = args.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const timeoutMs = args.timeoutMs ?? 600_000;
+  const pollMs = args.pollMs ?? 5_000;
+  const policy: TerminatePolicy = args.terminate ?? "never";
+  const conversationId = args.conversation;
+  const clientRequestId = args.clientRequestId ?? `chant-${randomUUID()}`;
+
+  const sent = await client("POST", `/api/conversations/${conversationId}/prompts`, { prompt: args.prompt, client_request_id: clientRequestId });
+  if (sent.status !== 200 && sent.status !== 201 && sent.status !== 202) throw refusal(conversationId, sent.status, sent.json);
+
+  let turn: TurnView | undefined;
+  const done = async (status: string, interruptedByDeadline: boolean): Promise<FountainPromptResult> => {
+    const terminate = policy === "always" || (policy === "on-deadline" && interruptedByDeadline);
+    if (terminate) await raw!("POST", `/api/conversations/${conversationId}/terminate`);
+    return {
+      conversationId,
+      clientRequestId,
+      ...(turn?.id ? { turnId: turn.id } : {}),
+      ...(turn?.turn_number !== undefined ? { turnNumber: turn.turn_number } : {}),
+      status,
+      interruptedByDeadline,
+      ...(turn?.limit_reason ? { limitReason: turn.limit_reason } : {}),
+      terminated: terminate,
+    };
+  };
+  const interrupt = () => raw!("POST", `/api/conversations/${conversationId}/interrupt`).catch(() => undefined);
+
+  const deadline = Date.now() + timeoutMs;
+  try {
+    while (Date.now() < deadline) {
+      turn = (await turnOf(client, conversationId, clientRequestId)) ?? turn;
+      if (turn?.status && ENDED_TURN_STATUSES.has(turn.status)) return await done(turn.status, false);
+      signal?.throwIfAborted();
+      await sleep(pollMs);
+    }
+  } catch (err) {
+    if (signal?.aborted) {
+      await interrupt();
+      if (policy !== "never") await raw!("POST", `/api/conversations/${conversationId}/terminate`).catch(() => undefined);
+    }
+    throw err;
+  }
+
+  // The cap: the turn ran past timeoutMs. Interrupting ends the turn and keeps the conversation.
+  await interrupt();
+  turn = (await turnOf(raw!, conversationId, clientRequestId)) ?? turn;
+  return done("interrupted", true);
+}

package/src/op/activities/index.ts

@@ -2,7 +2,8 @@
  * fountain Op activities — resolved by the core activity registry when a
  * project's `chant.config.ts` lists the `fountain` lexicon. Contributes
  * the native applier (`fountainApply` — direct REST against fountain's
- * API, no CLI, no state file) and the conversation runner (`fountainRun`).
+ * API, no CLI, no state file), the conversation runner (`fountainRun`) and
+ * the next turn on a conversation (`fountainPrompt`, #3356).
  */
 export {
   fountainApply,
@@ -33,3 +34,6 @@ export {
   PERSISTENT_DONE_STATUSES,
 } from "./fountain-run";
 export type { FountainRunArgs, FountainRunResult, ResolvedAgent, TerminatePolicy } from "./fountain-run";
+
+export { fountainPrompt } from "./fountain-prompt";
+export type { FountainPromptArgs, FountainPromptResult } from "./fountain-prompt";

package/src/skills/chant-fountain-locked-sandboxes.md

@@ -31,4 +31,4 @@ The environment's config is the enforcement boundary, so watch it: `chant lifecy
 
 ## Running conversations
 
-Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), and waits for the turn to end. What "end" means, and what happens to the machine, follows the agent's `sandbox_mode`: an `ephemeral` agent's conversation is polled for a terminal status and terminated on deadline, same as before; a `persistent` agent's (a `Steward` or `Box`) conversation settles on `idle` once its turn ends — machine still up for the next turn — so `fountainRun` reads the turn back and returns its outcome (`completed | failed | interrupted`) without terminating anything, by default. Pass `terminate: "on-deadline" | "always"` to opt a persistent agent's run back into ending the machine. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.
+Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), and waits for the turn to end. What "end" means, and what happens to the machine, follows the agent's `sandbox_mode`: an `ephemeral` agent's conversation is polled for a terminal status and terminated on deadline, same as before; a `persistent` agent's (a `Steward` or `Box`) conversation settles on `idle` once its turn ends — machine still up for the next turn — so `fountainRun` reads the turn back and returns its outcome (`completed | failed | interrupted`) without terminating anything, by default. Pass `terminate: "on-deadline" | "always"` to opt a persistent agent's run back into ending the machine. To add a turn to a conversation that already exists, use `fountainPrompt` with the conversation's id: it sends the prompt on the same session and waits for that turn, interrupting it at `timeoutMs`. It cannot reach a terminated conversation (fountain answers 410), so run the earlier turn with `terminate: "never"`, and it cannot narrow tools for one turn: that is the agent's `permission_policy`, set at launch. Interrupts and permission answers on their own are fountain's own conversations API.