@tai42/api-client 13.3.0 → 15.0.0

package/src/client.ts

@@ -65,9 +65,9 @@ export interface ApiKeyBody {
   // `null` is an explicit clear on edit (PATCH-style PUT): absent preserves the
   // stored policy data, `null` wipes it. Create never sends `null`.
   readonly policy_data?: Record<string, unknown> | null;
-  readonly condition?: string | null;
-  readonly condition_id?: string | null;
-  readonly condition_kwargs?: Record<string, unknown> | null;
+  // The access-control condition: an authored templated-text value (inline content
+  // or a stored template id), or `null` to explicitly clear it on edit.
+  readonly condition?: s.TemplatedText | null;
 }
 
 /**
@@ -82,16 +82,13 @@ export interface ClaimLinkBody {
 }
 
 /**
- * Body for the fail-closed jq guard (POST `/api/auth/validate-condition`).
- * `condition` (inline jq) and `condition_id` (named template) are mutually
- * exclusive — send exactly one. `sample_context` is a `JqAuthContext`-shaped
- * sample; when present the guard also evaluates the condition against it and
- * returns the boolean `result` (else `result` is `null`).
+ * Body for the fail-closed jq guard (POST `/api/auth/validate-condition`). The guard
+ * compile-checks the inline jq `condition` the author typed. `sample_context` is a
+ * `JqAuthContext`-shaped sample; when present the guard also evaluates the condition
+ * against it and returns the boolean `result` (else `result` is `null`).
  */
 export interface ValidateConditionBody {
   readonly condition?: string;
-  readonly condition_id?: string;
-  readonly condition_kwargs?: Record<string, unknown>;
   readonly sample_context?: Record<string, unknown>;
 }
 
@@ -197,6 +194,8 @@ export interface CreatePresetBody {
   readonly extensions?: readonly s.PresetExtensionElement[][];
   readonly output_schema?: Record<string, unknown> | null;
   readonly input_schema?: Record<string, unknown> | null;
+  // The optional door-layer state binding applied around every run of this preset.
+  readonly state_binding?: s.StateBinding | null;
 }
 
 /**
@@ -205,10 +204,11 @@ export interface CreatePresetBody {
  * sentinel is uniform: omitted carries the active version's value forward; an
  * explicit `[]` clears `extensions`, and an explicit `null` clears `output_schema`
  * or `input_schema`. `input_schema` is the optional author-set input JSON Schema and
- * follows the same carry-forward sentinel as `output_schema`. `description` carries
- * forward when omitted; an explicit non-empty string sets it (the API rejects an
- * explicit empty one). Categorization tags are not a version field — they live in the
- * tool_meta overlay.
+ * follows the same carry-forward sentinel as `output_schema`. `state_binding` is the
+ * optional door-layer binding and follows the same sentinel: omitted carries the active
+ * one forward, an explicit `null` clears it. `description` carries forward when omitted;
+ * an explicit non-empty string sets it (the API rejects an explicit empty one).
+ * Categorization tags are not a version field — they live in the tool_meta overlay.
  */
 export interface SavePresetVersionBody {
   readonly fixed_kwargs?: Record<string, unknown>;
@@ -216,6 +216,7 @@ export interface SavePresetVersionBody {
   readonly extensions?: readonly s.PresetExtensionElement[][];
   readonly output_schema?: Record<string, unknown> | null;
   readonly input_schema?: Record<string, unknown> | null;
+  readonly state_binding?: s.StateBinding | null;
 }
 
 /**
@@ -233,6 +234,10 @@ export interface ValidatePresetBody {
   readonly extensions?: readonly s.PresetExtensionElement[][];
   readonly output_schema?: Record<string, unknown> | null;
   readonly input_schema?: Record<string, unknown> | null;
+  // The optional door-layer state binding to dry-run — validated (never mounted) by the
+  // same checks the write would run. In VERSION mode it follows the save-version sentinel:
+  // omitted carries the active binding forward, an explicit `null` clears it.
+  readonly state_binding?: s.StateBinding | null;
 }
 
 /**
@@ -520,8 +525,8 @@ export interface StateDeclarationBody {
   readonly retention_days?: number | null;
 }
 
-/** A state-module document write body (`PUT /api/state-modules/{name}`, the platform half). */
-export interface StateModuleBody {
+/** A state-template document write body (`PUT /api/state-templates/{name}`, the platform half). */
+export interface StateTemplateBody {
   readonly name: string;
   readonly description?: string;
   readonly parameters?: Record<string, unknown>;
@@ -531,11 +536,15 @@ export interface StateModuleBody {
   readonly trace?: Record<string, unknown>;
 }
 
-/** A module mount / re-mount body (`PUT|PATCH /api/states/{name}/mounts/{module}`). */
-export interface StateMountBody {
+/** A template attach / re-attach body (`PUT|PATCH /api/states/{name}/attachments/{template}`). */
+export interface StateAttachmentBody {
   readonly path?: string[];
   readonly parameters?: Record<string, unknown>;
   readonly declarations?: Record<string, unknown>;
+  // Reconcile directive for a re-attach that would orphan open records: retry with
+  // `{ orphans: "close", resolution: "<name>" }` to close them (the server refuses
+  // without it). Omitted on a first attach.
+  readonly options?: Record<string, unknown>;
 }
 
 /** The four-part subject a record route addresses in its path. */
@@ -565,6 +574,22 @@ function stateRecordPath(name: string, subject: StateSubjectRef): string {
   );
 }
 
+/**
+ * Encode a template jq's declared params as JSON query values: the record `template-jq`
+ * route reads each `?<param>=<json>` as a JSON-decoded argument, so a string, number,
+ * array or object round-trips faithfully. An `undefined` value is dropped (an
+ * omitted optional param).
+ */
+function encodeJqParams(params?: Record<string, unknown>): Record<string, string> | undefined {
+  if (params === undefined) return undefined;
+  const query: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    query[key] = JSON.stringify(value);
+  }
+  return query;
+}
+
 export function createApiClient(config: ApiConfig) {
   const req = <S extends Parameters<typeof apiRequest>[2]>(
     path: string,
@@ -676,7 +701,7 @@ export function createApiClient(config: ApiConfig) {
     // -- states --------------------------------------------------------------
     // A state is a declared JSON document, one per subject. The list is the
     // management population; a single state read composes the declaration with its
-    // effective schema, regimes and mounts. Every record route addresses its subject
+    // effective schema, regimes and attachments. Every record route addresses its subject
     // as four percent-encoded path segments (see `stateRecordPath`).
     listStates: (signal?: AbortSignal) => req('/api/states', s.stateList, { signal }),
     getState: (name: string, signal?: AbortSignal) =>
@@ -693,28 +718,33 @@ export function createApiClient(config: ApiConfig) {
       req(`/api/states/${encodeSegment(name)}`, s.stateDeleted, { method: 'DELETE' }),
     getStateStats: (name: string, signal?: AbortSignal) =>
       req(`/api/states/${encodeSegment(name)}/stats`, s.stateStats, { signal }),
-    // -- state mounts --------------------------------------------------------
-    listStateMounts: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/mounts`, s.stateMountList, { signal }),
-    getStateMount: (name: string, module: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/mounts/${encodeSegment(module)}`, s.stateMount, {
-        signal,
-      }),
-    mountStateModule: (name: string, module: string, body: StateMountBody) =>
-      req(`/api/states/${encodeSegment(name)}/mounts/${encodeSegment(module)}`, s.stateMounted, {
-        method: 'PUT',
-        body,
-      }),
-    patchStateMount: (name: string, module: string, body: StateMountBody) =>
+    // -- state template attachments ------------------------------------------
+    listStateAttachments: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/attachments`, s.stateAttachmentList, { signal }),
+    getStateAttachment: (name: string, template: string, signal?: AbortSignal) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttachment,
+        { signal },
+      ),
+    attachStateTemplate: (name: string, template: string, body: StateAttachmentBody) =>
       req(
-        `/api/states/${encodeSegment(name)}/mounts/${encodeSegment(module)}`,
-        s.stateMountUpdated,
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttached,
+        { method: 'PUT', body },
+      ),
+    patchStateAttachment: (name: string, template: string, body: StateAttachmentBody) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttachmentUpdated,
         { method: 'PATCH', body },
       ),
-    unmountStateModule: (name: string, module: string) =>
-      req(`/api/states/${encodeSegment(name)}/mounts/${encodeSegment(module)}`, s.stateUnmounted, {
-        method: 'DELETE',
-      }),
+    detachStateTemplate: (name: string, template: string) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateDetached,
+        { method: 'DELETE' },
+      ),
     // -- state subjects + records -------------------------------------------
     listStateSubjects: (
       name: string,
@@ -740,11 +770,11 @@ export function createApiClient(config: ApiConfig) {
     // A subject with no document yet reads as `null` (a 200 `{data: null}`, the record
     // page's Create path) — never an error, so the schema is nullable.
     getStateRecord: (name: string, subject: StateSubjectRef, signal?: AbortSignal) =>
-      req(stateRecordPath(name, subject), s.recordView.nullable(), { signal }),
+      req(stateRecordPath(name, subject), s.stateRecord.nullable(), { signal }),
     putStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
-      req(stateRecordPath(name, subject), s.recordView, { method: 'PUT', body: data }),
+      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PUT', body: data }),
     patchStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
-      req(stateRecordPath(name, subject), s.recordView, { method: 'PATCH', body: data }),
+      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PATCH', body: data }),
     applyStateRecord: (
       name: string,
       subject: StateSubjectRef,
@@ -754,6 +784,35 @@ export function createApiClient(config: ApiConfig) {
         method: 'POST',
         body: { ops },
       }),
+    // Evaluate a template jq over the subject: each declared param is JSON-encoded into
+    // the query string (`?<param>=<json>`); the response is `{name, purpose, value}`. An
+    // `attachment.name` jq is percent-encoded as one path segment.
+    evalTemplateJq: (
+      name: string,
+      subject: StateSubjectRef,
+      jqName: string,
+      params?: Record<string, unknown>,
+      signal?: AbortSignal,
+    ) =>
+      req(
+        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        s.templateJqResult,
+        { signal, query: encodeJqParams(params) },
+      ),
+    // Apply an `update`-purpose template jq to the subject: `input` is the jq's argument,
+    // `op_id` its idempotency key (a replay is a no-op). The jq lands its op batch through
+    // the apply chokepoint. An `attachment.name` jq is percent-encoded as one path segment.
+    applyTemplateJq: (
+      name: string,
+      subject: StateSubjectRef,
+      jqName: string,
+      body?: { input?: unknown; op_id?: string },
+    ) =>
+      req(
+        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        s.templateJqApplyResult,
+        { method: 'POST', body: body ?? {} },
+      ),
     deleteStateRecord: (name: string, subject: StateSubjectRef) =>
       req(stateRecordPath(name, subject), s.recordErased, { method: 'DELETE' }),
     // `mode` is required server-side (`switch` drops, `merge` combines); the fold returns
@@ -780,19 +839,21 @@ export function createApiClient(config: ApiConfig) {
       }),
     stateConsumers: (name: string, signal?: AbortSignal) =>
       req(`/api/states/${encodeSegment(name)}/consumers`, s.stateConsumers, { signal }),
-    // -- state-module documents (top-level sibling collection) ---------------
-    listStateModules: (signal?: AbortSignal) =>
-      req('/api/state-modules', s.stateModuleList, { signal }),
-    getStateModule: (name: string, signal?: AbortSignal) =>
-      req(`/api/state-modules/${encodeSegment(name)}`, s.stateModuleDocument, { signal }),
-    putStateModule: (name: string, body: StateModuleBody, replace?: boolean) =>
-      req(`/api/state-modules/${encodeSegment(name)}`, s.stateModuleDocument, {
+    // -- state-template documents (top-level sibling collection) ---------------
+    listStateTemplates: (signal?: AbortSignal) =>
+      req('/api/state-templates', s.stateTemplateList, { signal }),
+    getStateTemplate: (name: string, signal?: AbortSignal) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, { signal }),
+    putStateTemplate: (name: string, body: StateTemplateBody, replace?: boolean) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, {
         method: 'PUT',
         body,
         query: replace === true ? { replace: 'true' } : undefined,
       }),
-    deleteStateModule: (name: string) =>
-      req(`/api/state-modules/${encodeSegment(name)}`, s.stateModuleDeleted, { method: 'DELETE' }),
+    deleteStateTemplate: (name: string) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDeleted, {
+        method: 'DELETE',
+      }),
     // -- state retention -----------------------------------------------------
     pruneStateRetention: () =>
       req('/api/state-retention/prune', s.stateRetentionPruned, { method: 'POST', body: {} }),
@@ -902,11 +963,11 @@ export function createApiClient(config: ApiConfig) {
     // root; those surface as loud errors, never a faked success.
     deleteTemplateDir: (path: string) =>
       req('/api/delete-template-dir', s.templateDirDeleted, { method: 'POST', body: { path } }),
-    renderTemplate: (body: {
-      content?: string;
-      template_id?: string;
-      kwargs?: Record<string, unknown>;
-    }) => req('/api/render-template', s.templateRendered, { method: 'POST', body }),
+    // Render one authored text — inline `content` OR a stored template `id`, plus its
+    // render `kwargs` — and parse the rendered output. The value is the shared
+    // `TemplatedText` (exactly one source); the route wraps it under `text`.
+    renderTemplate: (text: s.TemplatedText) =>
+      req('/api/render-template', s.templateRendered, { method: 'POST', body: { text } }),
     clearTemplatesCache: () =>
       req('/api/clear-templates-cache', s.templateCacheCleared, { method: 'POST' }),
 
@@ -1555,6 +1616,8 @@ export function createApiClient(config: ApiConfig) {
       tool_name: string;
       tool_kwargs: Record<string, unknown>;
       schedule_kwargs: Record<string, unknown>;
+      // The optional door-layer state binding applied around every fire of this schedule.
+      state_binding?: s.StateBinding | null;
     }) => req('/api/schedules', s.jsonValue, { method: 'POST', body }),
     deleteSchedule: (name: string) =>
       req(`/api/schedules/${encodeSegment(name)}`, s.jsonValue, { method: 'DELETE' }),

package/src/errors.ts

@@ -15,12 +15,26 @@ export class ApiError extends Error {
    * caller that does not ignores it.
    */
   readonly retryAfterSeconds?: number;
-  constructor(message: string, status: number, code?: string, retryAfterSeconds?: number) {
+  /**
+   * The full parsed error body (`{ error, code, …extra }`), when the failure carried a
+   * JSON body. Operations spread structured follow-up data beside the message (e.g. a
+   * reconcile refusal's `{ reconcile: true, orphans: [...] }`), so a UI keys its
+   * follow-up on this DATA, not on the prose. `undefined` when the body was not JSON.
+   */
+  readonly body?: unknown;
+  constructor(
+    message: string,
+    status: number,
+    code?: string,
+    retryAfterSeconds?: number,
+    body?: unknown,
+  ) {
     super(message);
     this.name = 'ApiError';
     this.status = status;
     this.code = code;
     this.retryAfterSeconds = retryAfterSeconds;
+    this.body = body;
   }
 }
 
@@ -34,8 +48,8 @@ export class ApiUnauthorizedError extends ApiError {
 
 /** A duplicate answer / alias collision etc. (HTTP 409). */
 export class ApiConflictError extends ApiError {
-  constructor(message: string) {
-    super(message, 409);
+  constructor(message: string, body?: unknown) {
+    super(message, 409, undefined, undefined, body);
     this.name = 'ApiConflictError';
   }
 }

package/src/http.ts

@@ -132,8 +132,10 @@ export async function apiRequest<S extends z.ZodType>(
   if (!response.ok) {
     const { message, code } = extractError(payload);
     const text = message ?? (response.statusText || 'request failed');
-    if (response.status === 409) throw new ApiConflictError(text);
-    throw new ApiError(text, response.status, code, retryAfter);
+    // The parsed body rides the error so a caller can key a follow-up on its structured
+    // fields (e.g. a reconcile refusal's `orphans`), never on the message prose.
+    if (response.status === 409) throw new ApiConflictError(text, payload);
+    throw new ApiError(text, response.status, code, retryAfter, payload);
   }
 
   if (!isDataEnvelope(payload)) {

package/src/index.ts

@@ -26,8 +26,8 @@ export type {
   SavePresetVersionBody,
   ValidatePresetBody,
   StateDeclarationBody,
-  StateModuleBody,
-  StateMountBody,
+  StateTemplateBody,
+  StateAttachmentBody,
   StateSubjectRef,
   StatePageQuery,
   ToolMetaPatch,
@@ -86,6 +86,7 @@ export type {
 } from './fleet-report';
 export * as schemas from './schemas';
 export type {
+  TemplatedText,
   ToolSchema,
   ToolMediaResult,
   ToolTagEntry,
@@ -109,13 +110,22 @@ export type {
   StateSubject,
   StateDeclaration,
   StateListItem,
-  StateMount,
+  StateAttachment,
   StateDetail,
   StateStats,
-  StateModuleDocument,
-  StateModuleListItem,
-  RecordView,
+  TemplateJq,
+  TemplateReconcile,
+  TemplateDeclarations,
+  StateTemplateDocument,
+  StateTemplateListItem,
+  StateInjection,
+  StateUpdate,
+  StateAttach,
+  StateBinding,
+  StateRecord,
   ApplyResult,
+  TemplateJqResult,
+  TemplateJqApplyResult,
   SubjectRow,
   SubjectPage,
   RecordSearchPage,
@@ -125,9 +135,9 @@ export type {
   ConsumerLink,
   ConsumerRow,
   StateConsumers,
-  StateMounted,
-  StateMountUpdated,
-  StateUnmounted,
+  StateAttached,
+  StateAttachmentUpdated,
+  StateDetached,
   StateFoldReport,
   StateRetentionPruned,
   FolderRecord,