@tai42/api-client 17.1.5 → 18.0.0

package/src/client/tools-client.ts

@@ -1,12 +1,16 @@
 /** Tool catalog, run, live-registry admin and tag sub-client. */
 import { encodeSegment } from '../http';
 import * as s from '../schemas';
+import type { StateSubject } from '../schemas/states';
 import { getToolRun, listToolRuns, submitToolRun, type SubmitToolRunArgs } from '../tool-runs';
 import type { Transport } from './transport';
 
 export interface RunToolArgs {
   readonly tool: string;
   readonly kwargs?: Record<string, unknown>;
+  /** The addressed subject an async park of this run indexes under. Omitted from
+   * the request body when unset, so a plain run (no subject) parks un-indexed. */
+  readonly subject?: StateSubject;
 }
 
 /**
@@ -32,11 +36,16 @@ export function toolsClient(t: Transport) {
     runTool: (args: RunToolArgs, signal?: AbortSignal) =>
       req('/api/run-tool', s.runToolResult, {
         method: 'POST',
-        // The backend's `/api/run-tool` door reads `{tool_name, arguments}` (the
-        // shape `read_tool_call` enforces and the background `/api/tool-runs`
+        // The backend's `/api/run-tool` door reads `{tool_name, arguments, subject}`
+        // (the shape `read_tool_call` enforces and the background `/api/tool-runs`
         // submit already sends). The SPA keeps `tool`/`kwargs` as its ergonomic
-        // arg names; map them onto the wire fields here.
-        body: { tool_name: args.tool, arguments: args.kwargs ?? {} },
+        // arg names; map them onto the wire fields here. `subject` rides only when
+        // set, so a plain run sends no subject.
+        body: {
+          tool_name: args.tool,
+          arguments: args.kwargs ?? {},
+          ...(args.subject !== undefined ? { subject: args.subject } : {}),
+        },
         signal,
       }),
 

package/src/generated/served-schemas.ts

@@ -60,7 +60,7 @@ export type UrlButtonParam = z.infer<typeof urlButtonParam>;
 export const accessPolicy = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "policy_data": z.record(z.string(), z.unknown()).default({}), "scopes": z.array(z.string()).default([]) });
 export type AccessPolicy = z.infer<typeof accessPolicy>;
 
-export const callbackSchema = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "expr": z.union([templatedText, z.null()]).default(null), "tool": z.string().default("") });
+export const callbackSchema = z.object({ "carried_kwargs": z.record(z.string(), z.unknown()).default({}), "condition": z.union([templatedText, z.null()]).default(null), "expr": z.union([templatedText, z.null()]).default(null), "tool": z.string().default("") });
 export type CallbackSchema = z.infer<typeof callbackSchema>;
 
 export const channelTemplate = z.object({ "body_parameters": z.array(z.string()).default([]), "buttons": z.array(z.unknown().superRefine((x, ctx) => {
@@ -98,16 +98,16 @@ export const channelTemplate = z.object({ "body_parameters": z.array(z.string())
   })).default([]), "header_media": z.union([mediaItem, z.null()]).default(null), "language": z.string(), "name": z.string() });
 export type ChannelTemplate = z.infer<typeof channelTemplate>;
 
-export const conversationRoute = z.object({ "callback_secret": z.union([z.string(), z.null()]).default(null), "callback_url": z.union([z.string(), z.null()]).default(null), "channel": z.union([z.string(), z.null()]).default(null), "door": z.enum(["api","channel"]), "error_reply_text": z.union([z.string().min(1).max(2000), z.null()]).default(null), "execution_key": z.string().min(1), "execution_key_fingerprint": z.string().min(1), "initial_mode": z.enum(["agent","manual"]).default("agent"), "locale": z.union([z.string(), z.null()]).default(null), "our_identity": z.union([z.string(), z.null()]).default(null), "overlap": overlapPolicy.default({"deliver":"one","running":"continue","settle_seconds":0}), "payload_expr": z.union([templatedText, z.null()]).default(null), "reply_expr": z.union([templatedText, z.null()]).default(null), "route_name": z.string(), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1), "turns_per_hour_override": z.union([z.number().int().gt(0), z.null()]).default(null) });
+export const conversationRoute = z.object({ "callback_secret": z.union([z.string(), z.null()]).default(null), "callback_url": z.union([z.string(), z.null()]).default(null), "cancel_expr": z.union([templatedText, z.null()]).default(null), "channel": z.union([z.string(), z.null()]).default(null), "door": z.enum(["api","channel"]), "error_reply_text": z.union([z.string().min(1).max(2000), z.null()]).default(null), "execution_key": z.string().min(1), "execution_key_fingerprint": z.string().min(1), "extras_expr": z.union([templatedText, z.null()]).default(null), "initial_mode": z.enum(["agent","manual"]).default("agent"), "locale": z.union([z.string(), z.null()]).default(null), "our_identity": z.union([z.string(), z.null()]).default(null), "overlap": overlapPolicy.default({"deliver":"one","running":"continue","settle_seconds":0}), "reply_expr": z.union([templatedText, z.null()]).default(null), "resume_expr": z.union([templatedText, z.null()]).default(null), "route_name": z.string(), "start_expr": z.union([templatedText, z.null()]).default(null), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1), "turns_per_hour_override": z.union([z.number().int().gt(0), z.null()]).default(null) });
 export type ConversationRoute = z.infer<typeof conversationRoute>;
 
-export const conversationRouteCreate = z.object({ "callback_url": z.union([z.string(), z.null()]).default(null), "channel": z.union([z.string(), z.null()]).default(null), "door": z.enum(["api","channel"]), "error_reply_text": z.union([z.string().min(1).max(2000), z.null()]).default(null), "execution_key": z.string().min(1), "initial_mode": z.enum(["agent","manual"]).default("agent"), "locale": z.union([z.string(), z.null()]).default(null), "our_identity": z.union([z.string(), z.null()]).default(null), "overlap": overlapPolicy.default({"deliver":"one","running":"continue","settle_seconds":0}), "payload_expr": z.union([templatedText, z.null()]).default(null), "reply_expr": z.union([templatedText, z.null()]).default(null), "route_name": z.string(), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1), "turns_per_hour_override": z.union([z.number().int().gt(0), z.null()]).default(null) });
+export const conversationRouteCreate = z.object({ "callback_url": z.union([z.string(), z.null()]).default(null), "cancel_expr": z.union([templatedText, z.null()]).default(null), "channel": z.union([z.string(), z.null()]).default(null), "door": z.enum(["api","channel"]), "error_reply_text": z.union([z.string().min(1).max(2000), z.null()]).default(null), "execution_key": z.string().min(1), "extras_expr": z.union([templatedText, z.null()]).default(null), "initial_mode": z.enum(["agent","manual"]).default("agent"), "locale": z.union([z.string(), z.null()]).default(null), "our_identity": z.union([z.string(), z.null()]).default(null), "overlap": overlapPolicy.default({"deliver":"one","running":"continue","settle_seconds":0}), "reply_expr": z.union([templatedText, z.null()]).default(null), "resume_expr": z.union([templatedText, z.null()]).default(null), "route_name": z.string(), "start_expr": z.union([templatedText, z.null()]).default(null), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1), "turns_per_hour_override": z.union([z.number().int().gt(0), z.null()]).default(null) });
 export type ConversationRouteCreate = z.infer<typeof conversationRouteCreate>;
 
-export const hookParams = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "execution_key": z.string().min(1), "execution_key_fingerprint": z.string().min(1), "expr": z.union([templatedText, z.null()]).default(null), "name": z.string().min(1), "state_binding": z.union([stateBinding, z.null()]).default(null), "subject": z.union([hookSubject, z.null()]).default(null), "tool": z.string().min(1), "tool_kwargs": z.record(z.string(), z.unknown()).default({}), "topic": z.string().min(1) });
+export const hookParams = z.object({ "cancel_expr": z.union([templatedText, z.null()]).default(null), "condition": z.union([templatedText, z.null()]).default(null), "execution_key": z.string().min(1), "execution_key_fingerprint": z.string().min(1), "extras_expr": z.union([templatedText, z.null()]).default(null), "name": z.string().min(1), "resume_expr": z.union([templatedText, z.null()]).default(null), "start_expr": z.union([templatedText, z.null()]).default(null), "state_binding": z.union([stateBinding, z.null()]).default(null), "subject": z.union([hookSubject, z.null()]).default(null), "tool": z.string().min(1), "tool_kwargs": z.record(z.string(), z.unknown()).default({}), "topic": z.string().min(1) });
 export type HookParams = z.infer<typeof hookParams>;
 
-export const hookRegister = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "execution_key": z.string().min(1), "expr": z.union([templatedText, z.null()]).default(null), "name": z.string().min(1), "state_binding": z.union([stateBinding, z.null()]).default(null), "subject": z.union([hookSubject, z.null()]).default(null), "tool": z.string().min(1), "tool_kwargs": z.record(z.string(), z.unknown()).default({}), "topic": z.string().min(1) });
+export const hookRegister = z.object({ "cancel_expr": z.union([templatedText, z.null()]).default(null), "condition": z.union([templatedText, z.null()]).default(null), "execution_key": z.string().min(1), "extras_expr": z.union([templatedText, z.null()]).default(null), "name": z.string().min(1), "resume_expr": z.union([templatedText, z.null()]).default(null), "start_expr": z.union([templatedText, z.null()]).default(null), "state_binding": z.union([stateBinding, z.null()]).default(null), "subject": z.union([hookSubject, z.null()]).default(null), "tool": z.string().min(1), "tool_kwargs": z.record(z.string(), z.unknown()).default({}), "topic": z.string().min(1) });
 export type HookRegister = z.infer<typeof hookRegister>;
 
 export const presetBody = z.object({ "base_tool": z.string(), "description": z.string().default(""), "extensions": z.array(z.array(z.union([z.string(), z.record(z.string(), z.unknown())]))).default([]), "fixed_kwargs": z.record(z.string(), z.unknown()).default({}), "input_schema": z.union([templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "output_schema": z.union([templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "state_binding": z.union([stateBinding, z.null()]).default(null) });

package/src/index.ts

@@ -76,6 +76,7 @@ export type {
   BackendInfo,
   BackupDocument,
   BackupImportReport,
+  CallerAsksEnvelope,
   Channels,
   ChannelTemplate,
   ClaimLinkCreated,
@@ -177,6 +178,8 @@ export type {
   Notification,
   Notifications,
   OAuthCompleteResult,
+  ParkedCallerAsk,
+  ParkedStatus,
   PatternEntry,
   PolicyBody,
   PolicyVersion,
@@ -235,6 +238,7 @@ export type {
   SubjectRow,
   SubMcpEntry,
   SubMcpMount,
+  SuspendedRunReceipt,
   TargetConversationConfig,
   TemplateDeclarations,
   TemplatedText,
@@ -257,6 +261,7 @@ export type {
   TriggerLinkList,
   TriggerLinkRecord,
   ValidateConditionResult,
+  VisitOutcome,
   WebEntryCode,
   WebEntryCodeMinted,
   WebEntryCodeRevoked,
@@ -274,6 +279,7 @@ export { readSseFrames, SseFrameParser } from './sse';
 export type {
   SubmitToolRunArgs,
   ToolRunListItem,
+  ToolRunParkAnswer,
   ToolRunRecord,
   ToolRunStatus,
   ToolRunSubmitResult,
@@ -282,6 +288,7 @@ export {
   isTerminalRunStatus,
   toolRunList,
   toolRunListItem,
+  toolRunParkAnswer,
   toolRunRecord,
   toolRunStatus,
   toolRunSubmitResult,

package/src/schemas/config.ts

@@ -6,10 +6,11 @@ export const envConfig = z.object({
   secret_keys: z.array(z.string()),
 });
 /**
- * `GET /api/config/mode` — the active config backend mode (`file` / `k8s`). The
- * skeleton emits only `config_mode`; `read_only` is a UI-side gate, tolerated-absent
- * and defaulting to `false` (writable) so a normal response never drifts, while a
- * genuinely read-only deployment can opt in by emitting `read_only: true`.
+ * `GET /api/config/mode` — the active config backend mode: `file`, or an installed
+ * provider's mode name such as `kubernetes`. The skeleton emits only `config_mode`;
+ * `read_only` is a UI-side gate, tolerated-absent and defaulting to `false` (writable)
+ * so a normal response never drifts, while a genuinely read-only deployment can opt in
+ * by emitting `read_only: true`.
  */
 export const configMode = z.object({
   config_mode: z.string(),

package/src/schemas/tools.ts

@@ -16,6 +16,57 @@ export const allToolSchemas = z.record(z.string(), toolSchema);
 
 export const runToolResult = jsonValue;
 
+/** The lifecycle status a parked interaction on a run's subject carries: a pending ask, an
+ * ask whose continuation is resuming, or a resolved run's waiting outcome (clean/failed). */
+export const parkedStatus = z.enum(['asking', 'running', 'finished', 'failed']);
+export type ParkedStatus = z.infer<typeof parkedStatus>;
+
+/**
+ * One parked caller-ask entry a synchronous run-tool call returns when the tool asked its
+ * CALLER (`to="caller"`) and parked. The full contract entry carries more fields; the panel
+ * reads the display subset here and tolerates the rest. `question` is the prompt, `payload`
+ * the structured value the ask handed the caller, `asked_by` the run chain that raised it.
+ */
+export const parkedCallerAsk = z.object({
+  id: z.string(),
+  status: parkedStatus,
+  to: z.enum(['user', 'caller']).nullish(),
+  question: z.string().nullish(),
+  payload: z.record(z.string(), z.unknown()).nullish(),
+  asked_by: z.array(z.string()).nullish(),
+});
+export type ParkedCallerAsk = z.infer<typeof parkedCallerAsk>;
+
+/** A synchronous run whose tool parked CALLER asks returns this envelope in place of a result:
+ * the full caller-ask entries under `asks`. An empty `asks` means the run parked with no open
+ * caller ask (only user asks remain). */
+export const callerAsksEnvelope = z.object({
+  asks: z.array(parkedCallerAsk),
+});
+export type CallerAsksEnvelope = z.infer<typeof callerAsksEnvelope>;
+
+/** The park receipt a synchronous run returns when its tool parked only USER asks: the
+ * suspension sentinel's ids, with no caller ask for the panel to act on. */
+export const suspendedRunReceipt = z.object({
+  interaction_id: z.string(),
+  interaction_ids: z.array(z.string()),
+  caller_interaction_ids: z.array(z.string()).default([]),
+});
+export type SuspendedRunReceipt = z.infer<typeof suspendedRunReceipt>;
+
+/** What one resume / take / cancel of a parked interaction did, as `resume_parked` /
+ * `cancel_parked` return it through run-tool. `kind` picks the payload: `result` (a final
+ * value in `result`), `asks` (new caller asks in `asks`), `parked` (only user asks remain),
+ * or `none` (nothing ran). `action` names the single non-cancel action taken. */
+export const visitOutcome = z.object({
+  action: z.enum(['resumed', 'taken', 'started', 'none']),
+  cancelled: z.array(z.string()).default([]),
+  kind: z.enum(['result', 'asks', 'parked', 'none']),
+  result: z.unknown().optional(),
+  asks: z.array(parkedCallerAsk).default([]),
+});
+export type VisitOutcome = z.infer<typeof visitOutcome>;
+
 /**
  * The MEDIA content shape a direct tool run may return — fastmcp's serialized
  * `Image`/`Audio` MediaBlock (`{ type, data: <base64>, mimeType }`). One recognised

package/src/tool-runs.ts

@@ -9,25 +9,30 @@
  *
  * The background surface detaches a run from its HTTP request: submit returns a
  * `run_id` immediately (202), then the caller POLLS the single-run GET until the
- * status is terminal (`succeeded | failed | lost`). The list GET returns the
- * recent runs for one tool — id/status/timestamps only, never `result`/`error`.
+ * status is terminal (`succeeded | failed | lost | parked`). The list GET returns
+ * the recent runs for one tool — id/status/timestamps only, never `result`/`error`.
  */
 import { z } from 'zod';
 
 import type { ApiConfig } from './http';
 import { apiRequest, encodeSegment } from './http';
+import type { StateSubject } from './schemas/states';
+import { callerAsksEnvelope, suspendedRunReceipt } from './schemas/tools';
 
 /** A run's lifecycle state. `lost` = the server restarted mid-run; the result is
- * unrecoverable. `running` is the only non-terminal state. */
-export const toolRunStatus = z.enum(['running', 'succeeded', 'failed', 'lost']);
+ * unrecoverable. `parked` = the run's tool async-parked; its `result` is the park
+ * answer (see {@link toolRunParkAnswer}). `running` is the only non-terminal state. */
+export const toolRunStatus = z.enum(['running', 'succeeded', 'failed', 'lost', 'parked']);
 
 /** `POST /api/tool-runs` → the handle for the detached run. */
 export const toolRunSubmitResult = z.object({
   run_id: z.string(),
 });
 
-/** `GET /api/tool-runs/{run_id}` → the full record. `result` is arbitrary JSON
- * (present only on `succeeded`); `error` is present only on `failed`. */
+/** `GET /api/tool-runs/{run_id}` → the full record. `result` is arbitrary JSON: the
+ * tool's own value on `succeeded`, the park answer ({@link toolRunParkAnswer}) on
+ * `parked`. `error` is present only on `failed`. `resumed_interactions` is the parked
+ * interaction ids the run resumed or took while it executed (`[]` when it resumed none). */
 export const toolRunRecord = z.object({
   run_id: z.string(),
   tool_name: z.string(),
@@ -36,6 +41,7 @@ export const toolRunRecord = z.object({
   finished_at: z.string().optional(),
   result: z.unknown().optional(),
   error: z.string().optional(),
+  resumed_interactions: z.array(z.string()).optional(),
 });
 
 /** One entry of `GET /api/tool-runs?tool_name=...` — id/status/timestamps only,
@@ -50,7 +56,16 @@ export const toolRunListItem = z.object({
 
 export const toolRunList = z.array(toolRunListItem);
 
+/**
+ * The `result` a `parked` record carries — the SAME park answer the synchronous run-tool
+ * door returns: either the caller-ask envelope `{asks: [...]}` (the tool asked its CALLER
+ * and parked) or the suspension receipt (the run parked only USER asks, ids only). A poller
+ * reads it to tell a caller-ask park from a user-only one, exactly as the sync door's caller does.
+ */
+export const toolRunParkAnswer = z.union([callerAsksEnvelope, suspendedRunReceipt]);
+
 export type ToolRunStatus = z.infer<typeof toolRunStatus>;
+export type ToolRunParkAnswer = z.infer<typeof toolRunParkAnswer>;
 export type ToolRunSubmitResult = z.infer<typeof toolRunSubmitResult>;
 export type ToolRunRecord = z.infer<typeof toolRunRecord>;
 export type ToolRunListItem = z.infer<typeof toolRunListItem>;
@@ -59,6 +74,9 @@ export type ToolRunListItem = z.infer<typeof toolRunListItem>;
 export interface SubmitToolRunArgs {
   readonly tool_name: string;
   readonly arguments?: Record<string, unknown>;
+  /** The addressed subject an async park of the detached run indexes under. Omitted
+   * from the request body when unset. */
+  readonly subject?: StateSubject;
 }
 
 /** Submit a tool for detached background execution; resolves with its `run_id`. */
@@ -69,7 +87,11 @@ export function submitToolRun(
 ): Promise<ToolRunSubmitResult> {
   return apiRequest(config, '/api/tool-runs', toolRunSubmitResult, {
     method: 'POST',
-    body: { tool_name: args.tool_name, arguments: args.arguments ?? {} },
+    body: {
+      tool_name: args.tool_name,
+      arguments: args.arguments ?? {},
+      ...(args.subject !== undefined ? { subject: args.subject } : {}),
+    },
     signal,
   });
 }