@tai42/api-client 13.3.0 → 15.0.0

package/src/schemas.ts

@@ -12,6 +12,35 @@ export const jsonValue: z.ZodType = z.unknown();
 /** A JSON Schema object (Pydantic-emitted). Permissive; parsed by the auto-form. */
 export const jsonSchema = z.record(z.string(), z.unknown());
 
+/**
+ * One authored-text value: either inline `content` (text written in place) or a
+ * stored template `id` (a template resource fetched and rendered), never both and
+ * never neither. `kwargs` are the render parameters and apply in BOTH cases — a
+ * prompt with placeholders needs its values whether it was typed inline or fetched.
+ * `.strict()` refuses any other key so a drifting field fails the parse loudly.
+ */
+export const templatedText = z
+  .object({
+    content: z.string().optional(),
+    id: z.string().optional(),
+    kwargs: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+  .refine((value) => (value.content === undefined) !== (value.id === undefined), {
+    message: 'A templated-text value sets exactly one of `content` or `id`.',
+  });
+export type TemplatedText = z.infer<typeof templatedText>;
+
+/**
+ * A templated-text value that must carry a source: inline `content` is non-empty, or
+ * a stored template `id` is chosen. Used where the platform contract requires a
+ * value (e.g. a state binding's subject, an update's adapter when present).
+ */
+export const requiredTemplatedText = templatedText.refine(
+  (value) => (value.id !== undefined ? value.id.length > 0 : (value.content ?? '').length > 0),
+  { message: 'Provide inline text or choose a stored template.' },
+);
+
 // -- tools -------------------------------------------------------------------
 
 export const toolNames = z.array(z.string());
@@ -115,8 +144,9 @@ export const presetExtensions = z.array(z.array(presetExtensionElement));
  * One preset as `GET /api/presets` returns it. Every preset is versioned, so
  * `active_version` is always an int; `conflicted` marks a QUARANTINED row (its
  * name collided with a foreign tool at boot — delete-only). `extensions` are the
- * ACTIVE version's extension combos and `output_schema` the optional author-set
- * output JSON Schema. Categorization tags live in the tool_meta overlay
+ * ACTIVE version's extension combos, `output_schema` the optional author-set
+ * output JSON Schema, and `input_schema` the optional author-set input JSON
+ * Schema. Categorization tags live in the tool_meta overlay
  * (`GET /api/tool-meta`), never on the record. A drift throws `ApiSchemaError`;
  * nothing is coerced.
  */
@@ -127,6 +157,7 @@ export const presetRecord = z.object({
   active_version: z.number(),
   extensions: presetExtensions,
   output_schema: z.record(z.string(), z.unknown()).nullable(),
+  input_schema: z.record(z.string(), z.unknown()).nullable(),
   conflicted: z.boolean(),
   // The human-readable cause a row is quarantined (its name collided with a
   // foreign tool at boot), or `null` when the row is not conflicted. Rendered
@@ -147,6 +178,79 @@ export const presetDetail = presetRecord.extend({
 });
 export type PresetDetail = z.infer<typeof presetDetail>;
 
+/**
+ * One input injection of a state binding: BEFORE the run, a value is produced and
+ * placed into the run input under `into` (the run-input field name). A template
+ * `input` jq (`template_jq`, named `name` or attachment-qualified `template.name`) reads the
+ * record — its input is the record (`.`), with declared params bound as `$params`; a
+ * custom `jq` reads `{record, input}` → the value. Exactly one of `template_jq`/`jq`
+ * carries the program; the other is `null`.
+ */
+export const stateInjection = z.object({
+  // `template_jq` names a program the attached state template ships; it is resolved
+  // through compiled programs, never rendered as text, so it stays a plain string.
+  template_jq: z.string().nullable().default(null),
+  jq: templatedText.nullable().default(null),
+  into: z.string(),
+});
+export type StateInjection = z.infer<typeof stateInjection>;
+
+/**
+ * One update of a state binding: AFTER the run, a template-relative op batch is
+ * applied through the store. A NAMED update (`template_jq`) runs the template `update`
+ * jq over `{record, input}` where `input` is built by `adapter` — a jq over
+ * `{output, input}` that constructs the update jq's declared input object. A custom
+ * `jq` runs over `{record, output, input}` → `[{op, path, value}]` and carries no
+ * adapter. `op_id` is an optional idempotency-key expression. Exactly one of
+ * `template_jq`/`jq` carries the program.
+ */
+export const stateUpdate = z.object({
+  // `template_jq` names a program the attached state template ships; resolved through
+  // compiled programs, never rendered as text, so it stays a plain string.
+  template_jq: z.string().nullable().default(null),
+  jq: templatedText.nullable().default(null),
+  // A named update's adapter is either an authored value or `null` (no adapter — the
+  // run input passes through). When present it must carry a source (the platform
+  // compile-checks a non-null adapter and refuses an empty one).
+  adapter: requiredTemplatedText.nullable().default(null),
+  op_id: templatedText.nullable().default(null),
+});
+export type StateUpdate = z.infer<typeof stateUpdate>;
+
+/**
+ * One attached state of a binding: the `state`, one or more `templates`
+ * (attach-on-use — attached to the state on the binding's save), the `subject_expr`
+ * (a jq yielding the record KEY — a bare key string OR a full subject object — that
+ * this binding reads and updates), an optional `scope_expr` (a boolean jq predicate;
+ * when it is false this state is skipped for the run), and the ordered
+ * `input_injections` (before the run) and `updates` (after it).
+ */
+export const stateAttach = z.object({
+  state: z.string(),
+  templates: z.array(z.string()).default([]),
+  // The platform contract enforces a subject that carries a source; an empty one is
+  // rejected here, never sent for the server to refuse.
+  subject_expr: requiredTemplatedText,
+  scope_expr: templatedText.nullable().default(null),
+  input_injections: z.array(stateInjection).default([]),
+  updates: z.array(stateUpdate).default([]),
+});
+export type StateAttach = z.infer<typeof stateAttach>;
+
+/**
+ * The one generic binding shape carried, optionally, on every runnable definition
+ * (a preset, a channel route, a schedule, a hook) and repeated per node by the
+ * flow engine. It attaches one or more states, each with its templates, subject,
+ * injections and updates. `null` on a definition means no binding. Mirrors the
+ * platform `StateBinding` document.
+ */
+export const stateBinding = z.object({
+  // At least one attached state: the platform contract refuses a zero-state binding, so
+  // "no binding" is spelled `null` on the definition, never `{ states: [] }`.
+  states: z.array(stateAttach).min(1),
+});
+export type StateBinding = z.infer<typeof stateBinding>;
+
 /** The full version body a preset stores under `kind="preset"`. */
 export const presetBody = z.object({
   base_tool: z.string(),
@@ -154,6 +258,10 @@ export const presetBody = z.object({
   fixed_kwargs: z.record(z.string(), z.unknown()),
   extensions: presetExtensions,
   output_schema: z.record(z.string(), z.unknown()).nullable(),
+  input_schema: z.record(z.string(), z.unknown()).nullable(),
+  // The optional door-layer state binding this preset applies around every run
+  // (`null` when the preset touches no state).
+  state_binding: stateBinding.nullable().default(null),
 });
 export type PresetBody = z.infer<typeof presetBody>;
 
@@ -1140,6 +1248,9 @@ export const conversationRoute = z.object({
   turns_per_hour_override: z.number().int().nullable().default(null),
   error_reply_text: z.string().nullable().default(null),
   execution_key_fingerprint: z.string(),
+  // The door-layer state binding the backend stores on the route's target config and
+  // returns on read (`null` when the route touches no state) — the edit form prefills it.
+  state_binding: stateBinding.nullable().default(null),
 });
 export type ConversationRoute = z.infer<typeof conversationRoute>;
 
@@ -1176,6 +1287,9 @@ export const conversationRouteCreate = z.object({
   callback_url: z.string().nullable().default(null),
   turns_per_hour_override: z.number().int().positive().nullable().default(null),
   error_reply_text: z.string().min(1).max(2000).nullable().default(null),
+  // The optional door-layer state binding this route applies around every turn's
+  // tool run (`null` when the route touches no state).
+  state_binding: stateBinding.nullable().default(null),
 });
 export type ConversationRouteCreate = z.infer<typeof conversationRouteCreate>;
 
@@ -1495,8 +1609,8 @@ export type Notifications = z.infer<typeof notifications>;
 
 // -- hooks -------------------------------------------------------------------
 // Shapes match tai42_contract.hooks.HookParams: a hook fires a `tool` on a `topic`,
-// optionally gated by a `condition` and shaped by an `expr` (each either an inline
-// spec or a registered id, with its own kwargs).
+// optionally gated by a `condition` and shaped by an `expr` (each an authored
+// templated-text value: inline content or a stored template id, with render kwargs).
 
 /** A fire door — who may trigger a path, not what the fire may do. A string enum. */
 export const triggerAuth = z.enum([
@@ -1532,14 +1646,11 @@ export const hookParams = z.object({
   // The optional state subject the fire targets; `null` leaves it with no ambient
   // state context (a state tool it calls must then carry an explicit subject).
   subject: hookSubject.nullable().default(null),
-  condition: z.string().nullable().default(null),
-  condition_id: z.string().nullable().default(null),
-  // The `*_kwargs` pair is non-optional in the contract (defaults to {}, never
-  // null) — unlike the sibling condition/expr string fields, which are nullable.
-  condition_kwargs: z.record(z.string(), z.unknown()).default({}),
-  expr: z.string().nullable().default(null),
-  expr_id: z.string().nullable().default(null),
-  expr_kwargs: z.record(z.string(), z.unknown()).default({}),
+  condition: templatedText.nullable().default(null),
+  expr: templatedText.nullable().default(null),
+  // The optional door-layer state binding this hook applies around its fire's tool
+  // run (`null` when the hook touches no state).
+  state_binding: stateBinding.nullable().default(null),
 });
 export type HookParams = z.infer<typeof hookParams>;
 
@@ -1718,16 +1829,14 @@ export type RoleGrants = z.infer<typeof roleGrants>;
  * read-only base-tier ceiling — the seeded jq `condition` plus `base_tier`
  * (`editor`/`viewer`, or `null` for the reserved `allow_all` admin). Layer 2 is the
  * editable per-tag `grants` map. `allow_all` (admin) carries an empty `grants` map
- * and reaches everything, un-lockable. `condition`/`condition_id`/`condition_kwargs`
- * are the base-tier jq — READ-ONLY here (no raw-jq authoring surface).
+ * and reaches everything, un-lockable. `condition` is the base-tier jq (an authored
+ * templated-text value) — READ-ONLY here (no raw-jq authoring surface).
  */
 export const roleBody = z.object({
   name: z.string(),
   description: z.string(),
   scopes: z.array(z.string()),
-  condition: z.string().nullable(),
-  condition_id: z.string().nullable(),
-  condition_kwargs: jsonValue.nullable(),
+  condition: templatedText.nullable(),
   base_tier: z.string().nullable(),
   allow_all: z.boolean(),
   grants: roleGrants,
@@ -1795,9 +1904,7 @@ export const tokensPayload = z.array(
     description: z.string(),
     scopes: z.array(z.string()),
     policy_data: jsonValue,
-    condition: z.string().nullable().optional(),
-    condition_id: z.string().nullable().optional(),
-    condition_kwargs: jsonValue.nullable().optional(),
+    condition: templatedText.nullable().optional(),
   }),
 );
 export type TokensPayload = z.infer<typeof tokensPayload>;
@@ -1977,15 +2084,13 @@ export type ValidateConditionResult = z.infer<typeof validateConditionResult>;
 /**
  * The enforced policy shape a version body carries. SECRET-ADJACENT — `condition`
  * can reveal auth logic, so its fixtures are hand-authored, never captured.
- * `condition`/`condition_id` are mutually exclusive at author time; both are
- * nullable here because whichever mode is unused is stored as `null`.
+ * `condition` is an authored templated-text value (inline content or a stored
+ * template id); `null` when the policy carries no condition.
  */
 export const policyBody = z.object({
   scopes: z.array(z.string()),
   policy_data: jsonValue,
-  condition: z.string().nullable(),
-  condition_id: z.string().nullable(),
-  condition_kwargs: jsonValue.nullable(),
+  condition: templatedText.nullable(),
 });
 export type PolicyBody = z.infer<typeof policyBody>;
 
@@ -2613,11 +2718,11 @@ export { toolRunSubmitResult, toolRunRecord, toolRunList } from './tool-runs';
 
 // -- states ------------------------------------------------------------------
 // Shapes mirror tai42_contract.states.models: a declared JSON document, one per
-// subject. The base document, module fragments, write regimes and effective schema
+// subject. The base document, template fragments, write regimes and effective schema
 // are permissive JSON records — the auto-form and JsonTree interpret them at runtime;
-// a drift throws ApiSchemaError. Fields that WP-3's router is finishing concurrently
-// (`effective_schema`, `regimes`, list/stats derived columns) are modelled optional so
-// a server that has not yet composed them still parses.
+// a drift throws ApiSchemaError. Server-composed fields (`effective_schema`, `regimes`,
+// list/stats derived columns) are modelled optional so a response that omits them still
+// parses.
 
 /** One addressed subject: the conversation-target scope plus the (kind, key) within it. */
 export const stateSubject = z.object({
@@ -2628,12 +2733,12 @@ export const stateSubject = z.object({
 });
 export type StateSubject = z.infer<typeof stateSubject>;
 
-/** One absolute write-regime rule composed over the mounts: `{path, regime}`, permissive. */
+/** One absolute write-regime rule composed over the attachments: `{path, regime}`, permissive. */
 export const stateRegime = z.record(z.string(), z.unknown());
 
 /**
  * A declared state served on every read. `schema` is the base JSON Schema;
- * `effective_schema` (the base composed with every mounted module's fragment) and
+ * `effective_schema` (the base composed with every attached template's fragment) and
  * `regimes` (the absolute write-regime rules) are platform-COMPUTED and served on every
  * read — modelled optional so a write body that omits them, or a server yet to compose
  * them, still parses. A drift throws ApiSchemaError.
@@ -2662,19 +2767,19 @@ export const stateListItem = stateDeclaration.extend({
 export type StateListItem = z.infer<typeof stateListItem>;
 export const stateList = z.array(stateListItem);
 
-/** One module mount on a state: where the fragment lands + its param/declaration values. */
-export const stateMount = z.object({
-  module: z.string(),
+/** One template attachment on a state: where the fragment lands + its param/declaration values. */
+export const stateAttachment = z.object({
+  template: z.string(),
   path: z.array(z.string()),
   parameters: z.record(z.string(), z.unknown()).default({}),
   declarations: z.record(z.string(), z.unknown()).default({}),
 });
-export type StateMount = z.infer<typeof stateMount>;
-export const stateMountList = z.array(stateMount);
+export type StateAttachment = z.infer<typeof stateAttachment>;
+export const stateAttachmentList = z.array(stateAttachment);
 
-/** `GET /api/states/{name}` — the declaration (with effective schema + regimes) plus mounts. */
+/** `GET /api/states/{name}` — the declaration (with effective schema + regimes) plus attachments. */
 export const stateDetail = stateDeclaration.extend({
-  mounts: z.array(stateMount).default([]),
+  attachments: z.array(stateAttachment).default([]),
 });
 export type StateDetail = z.infer<typeof stateDetail>;
 
@@ -2692,34 +2797,84 @@ export const stateStats = z.object({
 });
 export type StateStats = z.infer<typeof stateStats>;
 
-/** The platform half of a state-module document (mirrors StateModuleDocument). */
-export const stateModuleDocument = z.object({
-  kind: z.literal('state-module').default('state-module'),
+/**
+ * One template jq: `jq` is a program over the subject's attached subtree, authored as a
+ * templated text (inline `content` or a stored template `id`); its `purpose` is either
+ * `input` (a read-only program feeding a tool argument) or `update` (a program returning
+ * an op batch that mutates the record). `params` are its declared argument names;
+ * `reads`/`writes` are the template-relative record paths an `update` declares, each a
+ * list of key segments; `description` is the human label.
+ */
+export const templateJq = z.object({
+  description: z.string().default(''),
+  purpose: z.enum(['input', 'update']),
+  params: z.array(z.string()).default([]),
+  reads: z.array(z.array(z.string())).default([]),
+  writes: z.array(z.array(z.string())).default([]),
+  jq: templatedText,
+});
+export type TemplateJq = z.infer<typeof templateJq>;
+
+/**
+ * How a declarations edit settles open records: `orphans` returns the items a record
+ * orphans against the new declarations, `close` builds the op batch that closes one
+ * orphan, `resolutions` names the resolutions a close may name — each a templated-text
+ * jq program (inline `content` or a stored template `id`).
+ */
+export const templateReconcile = z.object({
+  orphans: templatedText,
+  close: templatedText,
+  resolutions: templatedText,
+});
+export type TemplateReconcile = z.infer<typeof templateReconcile>;
+
+/**
+ * A template's declarations section: `schema` is the JSON schema of the static values an
+ * attachment stores, and `check` is an optional attach-time predicate authored as a
+ * templated text (inline `content` or a stored template `id`), `null` when the template
+ * declares none.
+ */
+export const templateDeclarations = z.object({
+  schema: jsonSchema,
+  check: templatedText.nullable().default(null),
+});
+export type TemplateDeclarations = z.infer<typeof templateDeclarations>;
+
+/**
+ * The platform half of a state-template document (mirrors StateTemplateDocument).
+ * `template_jq` maps a name to its definition (each carrying its `purpose`);
+ * `reconcile` is the settle policy; `declarations` is the static-values section — all
+ * optional (`null` when the template declares none).
+ */
+export const stateTemplateDocument = z.object({
+  kind: z.literal('state-template').default('state-template'),
   name: z.string(),
   description: z.string().default(''),
   parameters: z.record(z.string(), z.unknown()).default({}),
   schema: jsonSchema,
   regimes: z.array(stateRegime).default([]),
-  declarations: z.record(z.string(), z.unknown()).nullable().default(null),
+  declarations: templateDeclarations.nullable().default(null),
   trace: z.record(z.string(), z.unknown()).default({}),
+  template_jq: z.record(z.string(), templateJq).nullable().default(null),
+  reconcile: templateReconcile.nullable().default(null),
 });
-export type StateModuleDocument = z.infer<typeof stateModuleDocument>;
+export type StateTemplateDocument = z.infer<typeof stateTemplateDocument>;
 
 /**
- * One row of `GET /api/state-modules`. The module document plus the two derived columns
- * the Modules tab shows: `mounted_on` (how many states mount it — a delete is refused
- * while > 0) and `shipped_default` (a platform-shipped module). ASSUMED derived fields
- * (WP-3 owns the list router); the document fields are verbatim.
+ * One row of `GET /api/state-templates`. The template document plus the two derived columns
+ * the Templates tab shows: `attached_to` (how many states attach it — a delete is refused
+ * while > 0) and `shipped_default` (a platform-shipped template). Both are server-derived
+ * columns; the document fields are verbatim.
  */
-export const stateModuleListItem = stateModuleDocument.extend({
-  mounted_on: z.number().default(0),
+export const stateTemplateListItem = stateTemplateDocument.extend({
+  attached_to: z.number().default(0),
   shipped_default: z.boolean().default(false),
 });
-export type StateModuleListItem = z.infer<typeof stateModuleListItem>;
-export const stateModuleList = z.array(stateModuleListItem);
+export type StateTemplateListItem = z.infer<typeof stateTemplateListItem>;
+export const stateTemplateList = z.array(stateTemplateListItem);
 
 /** A read record: the state, its subject, the document + monotonic seq, and any fold. */
-export const recordView = z.object({
+export const stateRecord = z.object({
   state: z.string(),
   subject: stateSubject,
   data: z.record(z.string(), z.unknown()).default({}),
@@ -2727,7 +2882,7 @@ export const recordView = z.object({
   canonical_subject: stateSubject,
   folded_from: z.array(stateSubject).default([]),
 });
-export type RecordView = z.infer<typeof recordView>;
+export type StateRecord = z.infer<typeof stateRecord>;
 
 /** The outcome of an `apply` (a delta batch): whether it applied + the resulting doc. */
 export const applyResult = z.object({
@@ -2738,6 +2893,33 @@ export const applyResult = z.object({
 });
 export type ApplyResult = z.infer<typeof applyResult>;
 
+/**
+ * `GET …/template-jq/{name}` — the evaluated template jq's `name`, its `purpose`, and
+ * its `value` (the `input` jq's read). GET evaluates ONLY an `input`-purpose jq; a GET
+ * on an `update`-purpose name is refused with 422, so the result's purpose is always
+ * `input`.
+ */
+export const templateJqResult = z.object({
+  name: z.string(),
+  purpose: z.literal('input'),
+  value: z.unknown(),
+});
+export type TemplateJqResult = z.infer<typeof templateJqResult>;
+
+/**
+ * `POST …/template-jq/{name}` — the applied template jq's outcome. The jq lands an op
+ * batch through the same `apply` chokepoint as a delta, so `applied`/`data`/`seq`/`skipped`
+ * carry that outcome.
+ */
+export const templateJqApplyResult = z.object({
+  name: z.string(),
+  applied: z.boolean(),
+  data: z.record(z.string(), z.unknown()).nullable().default(null),
+  seq: z.number().nullable().default(null),
+  skipped: z.array(z.record(z.string(), z.unknown())).default([]),
+});
+export type TemplateJqApplyResult = z.infer<typeof templateJqApplyResult>;
+
 /**
  * One paged subject row: the addressed `subject` plus its record's last-write
  * `updated_at` — epoch seconds (the store's `extract(epoch FROM updated_at)`), served
@@ -2831,29 +3013,29 @@ export type StateConsumers = z.infer<typeof stateConsumers>;
 /** `DELETE /api/states/{name}` — the removed state. */
 export const stateDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
 
-/** `PUT /api/states/{name}/mounts/{module}` — the module now mounted on the state. */
-export const stateMounted = z.object({
-  mounted: z.literal(true),
+/** `PUT /api/states/{name}/attachments/{template}` — the template now attached to the state. */
+export const stateAttached = z.object({
+  attached: z.literal(true),
   state: z.string(),
-  module: z.string(),
+  template: z.string(),
 });
-export type StateMounted = z.infer<typeof stateMounted>;
+export type StateAttached = z.infer<typeof stateAttached>;
 
-/** `PATCH /api/states/{name}/mounts/{module}` — the mount whose declarations were rewritten. */
-export const stateMountUpdated = z.object({
+/** `PATCH /api/states/{name}/attachments/{template}` — the attachment whose declarations were rewritten. */
+export const stateAttachmentUpdated = z.object({
   updated: z.literal(true),
   state: z.string(),
-  module: z.string(),
+  template: z.string(),
 });
-export type StateMountUpdated = z.infer<typeof stateMountUpdated>;
+export type StateAttachmentUpdated = z.infer<typeof stateAttachmentUpdated>;
 
-/** `DELETE /api/states/{name}/mounts/{module}` — the module unmounted from the state. */
-export const stateUnmounted = z.object({
-  unmounted: z.literal(true),
+/** `DELETE /api/states/{name}/attachments/{template}` — the template detached from the state. */
+export const stateDetached = z.object({
+  detached: z.literal(true),
   state: z.string(),
-  module: z.string(),
+  template: z.string(),
 });
-export type StateUnmounted = z.infer<typeof stateUnmounted>;
+export type StateDetached = z.infer<typeof stateDetached>;
 
 /**
  * `POST /api/states/{name}/records/.../fold` — the fold report: the `mode`, the
@@ -2869,8 +3051,8 @@ export const stateFoldReport = z.object({
 });
 export type StateFoldReport = z.infer<typeof stateFoldReport>;
 
-/** `DELETE /api/state-modules/{name}` — the removed module document. */
-export const stateModuleDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
+/** `DELETE /api/state-templates/{name}` — the removed template document. */
+export const stateTemplateDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
 
 /** `DELETE /api/states/{name}/records/...` — the erased record marker. */
 export const recordErased = z.object({ erased: z.literal(true) });