stitchkit 0.58.0 → 0.59.1

package/dist/tools/cli.d.ts

@@ -1,11 +1,12 @@
 import type { ServiceDef, StitchLogger } from '../server/types';
 import { type CliCommandDefinition } from './cli-command';
 import { type ExitCodeMap } from './cli-format';
+import { type CliPresentationPolicyConfig } from './cli-policy';
 import { type CliWaitConfig } from './cli-wait';
 import { type ErrorHintFn, type ToolCallHooks, type ToolLifecycle } from './execute';
 import type { RuntimeToolDefinition } from './runtime-tool';
 export type CliSurfaceSource<TAuth, TValue> = readonly TValue[] | ((auth: Awaited<TAuth> | undefined) => readonly TValue[]);
-export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>> {
+export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>> extends CliPresentationPolicyConfig {
     /** Program name — shown in help and unknown-command messages. */
     name: string;
     /** Program version — printed by `--version`. */

package/dist/tools/cli.d.ts.map

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

package/dist/tools.d.ts

@@ -6,6 +6,7 @@ export { type AdaptedContractAsyncOperationConfig, type AdaptedContractAsyncOper
 export { type CliConfig, type CliSurfaceSource, createCli } from './tools/cli';
 export { type CliCommandContext, type CliCommandDefinition, type CliCommandDefinitionBase, type CliCommandDefinitionWithOutput, type CliCommandDefinitionWithoutOutput, defineCliCommand, } from './tools/cli-command';
 export type { ExitCodeMap } from './tools/cli-format';
+export type { CliPresentationPolicyConfig } from './tools/cli-policy';
 export type { CliWaitConfig } from './tools/cli-wait';
 export { coerceJsonArgs } from './tools/coerce';
 export { type DefineDownloadToolConfig, defineDownloadTool, } from './tools/define-download-tool';

package/dist/tools.d.ts.map

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

package/dist/tools.js

@@ -24,7 +24,7 @@ import {
   formatToolError,
   readCapped,
   runWaitOperation
-} from "./index-zk5zn2nh.js";
+} from "./index-3nwng7hs.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,

package/llms-full.txt

@@ -3500,29 +3500,40 @@ provide one database transaction driver:
 ```ts
 const store = createAgentRuntimeStore({
   transaction: work => db.transaction(tx => work(tx)),
-  state: {
-    load: (tx, conversationId) => loadRuntimeState(tx, conversationId),
-    compareAndSwap: (tx, operation) => casRuntimeState(tx, operation),
+  head: {
+    load: (tx, conversationId) => loadRuntimeHead(tx, conversationId),
+    compareAndSwap: (tx, operation) => casRuntimeHead(tx, operation),
+  },
+  runs: {
+    load: (tx, identity) => loadRun(tx, identity),
+    loadByAssistantMessageId: (tx, identity) => loadRunByAssistant(tx, identity),
+    loadMany: (tx, identities) => loadRuns(tx, identities),
+    listActive: (tx, conversationId) => listActiveRuns(tx, conversationId),
+    save: (tx, record) => saveRun(tx, record),
+  },
+  admissions: {
+    load: (tx, identity) => loadAdmission(tx, identity),
+    loadByInputMessageId: (tx, identity) => loadAdmissionByInput(tx, identity),
+    create: (tx, receipt) => createAdmission(tx, receipt),
   },
   history: {
     load: (tx, conversationId) => loadCanonicalMessages(tx, conversationId),
-    loadById: (tx, identity) => loadActiveOrArchivedMessage(tx, identity),
     apply: (tx, mutation) => applyCanonicalHistoryMutation(tx, mutation),
   },
   scanRecoverable: page => scanRecoverableRuns(page),
 })
 ```
 
-The same opaque `tx` reaches state and history callbacks. The adapter maps rows
+The same opaque `tx` reaches head, run, admission and history callbacks. The adapter maps rows
 and supplies atomicity; Stitchkit owns transition validation and revision
 arithmetic. The executable reference is
 [`examples/agent-store-prisma/adapter.ts`](../../examples/agent-store-prisma/adapter.ts).
 `compareAndSwap` returns either `{ outcome: 'applied' }` or
-`{ outcome: 'conflict', actualVersion }`; on a winning write it also persists the
-framework-provided `recoverable` descriptors in the same transaction. Recovery
-scans that bounded index instead of loading every aggregate. Compaction may hide
-rows from `history.load`, but `history.loadById` must retain canonical admitted
-inputs for durable duplicate receipts.
+`{ outcome: 'conflict', actualVersion }`. The head contains only schema version,
+conversation identity and monotonic version. Runs and admission receipts are normalized records;
+recovery queries active run states directly instead of maintaining a second projection.
+An admission receipt retains its canonical input, and a terminal run retains its canonical
+assistant, so physical product-history compaction cannot break idempotent retries.
 
 ## Durable order
 
@@ -3559,8 +3570,13 @@ Durably queued records rejected from the local queue remain recoverable through
 
 Use `await runtime.interrupt({ conversationId, runId })` when the interruption
 must be durable: it first commits `interrupt_requested`, then aborts the local
-coordinator signal. `runtime.stop(key)` is the process-local signal-only escape
-hatch.
+coordinator signal. If provider completion races that revision change, the terminal path reloads
+the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned
+`interrupt_requested` run is committed as `interrupted`, and unrelated aggregate-head conflicts
+remain retriable while the run is active with the same owner and fencing token. A stale owner or
+fencing token remains a conflict. Only the execution that applies the terminal mutation emits the
+terminal event and operator metrics; a loser settles from canonical state without republishing it.
+`runtime.stop(key)` is the process-local signal-only escape hatch.
 
 ## Store operations
 
@@ -3868,6 +3884,32 @@ validation, dry-run, error envelopes and exit mapping, but deliberately have no
 fake service/action/scope/method identity, lifecycle or tool hooks and never
 appear in MCP/Agent manifests.
 
+A native command with a declared output may also own its final terminal
+presentation and successful process status. Both callbacks receive the exact
+Zod output type and run only after output validation; help, dry-run and failed
+validation never invoke them:
+
+```ts
+const doctor = defineCliCommand({
+  name: 'doctor',
+  description: 'Inspect local health',
+  input: z.object({}),
+  output: z.object({ status: z.enum(['ok', 'degraded']) }),
+  handler: () => ({ status: 'degraded' }),
+  present: ({ result, options }) =>
+    options.json ? `${JSON.stringify(result)}\n` : `STATUS ${result.status}\n`,
+  exitCode: (result) => result.status === 'degraded' ? 1 : 0,
+})
+```
+
+`present` returns the exact stdout bytes, which Stitchkit writes once. Without
+it the canonical JSON output is unchanged. `exitCode` classifies a successfully
+validated result and must return an integer in `0..255`; failed `ToolResult`
+envelopes and the application-wide `exitCodes` mapping remain authoritative for
+failures. A throwing callback, invalid status or non-string presenter becomes a
+normalized `INTERNAL_SERVER_ERROR`, never partial success output. Void native
+commands cannot declare either callback.
+
 `--version`, a selected native command and its command help run before
 `resolveAuth`, services, context or runtime-tool factories. Top-level help is
 also credential-free when managed surfaces are static. A dynamic factory must
@@ -3894,9 +3936,52 @@ string, the schema says what it should be:
 | `z.object({...})`    | `--opts '{"k":"v"}'` (JSON) or `--opts.k v`    |
 | `.optional()` / `.default()` | not required                           |
 
-Positional arguments fill non-boolean fields in declaration order, so
-`myapp generate "a fox"` is `--prompt "a fox"`. A piped value fills the first
-unset field: `echo "a fox" | myapp generate`.
+Without presentation configuration, positional arguments fill non-boolean
+fields in declaration order, so `myapp generate "a fox"` is
+`--prompt "a fox"`. A piped value fills the first required unset field:
+`echo "a fox" | myapp generate`.
+
+For a stable shell grammar, declare the default command, short aliases and the
+exact positional fields on `createCli`:
+
+```ts
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  services,
+  commands: [doctor],
+  defaultCommand: 'logs',
+  optionAliases: {
+    logs: { f: 'follow', n: 'lines' },
+  },
+  positionals: {
+    logs: ['target'],       // `lines` is option-only
+    doctor: [],             // no argv positionals
+  },
+})
+```
+
+Now `myapp`, `myapp --json` and `myapp logs --json` select `logs`;
+`myapp -f -n 100 --target api` maps to
+`logs --follow --lines 100 --target api`. A leading non-option token remains an
+explicit command so typos stay loud rather than becoming ambiguous default
+positionals; use an explicit `myapp logs api` when passing positionals. Leading
+framework globals may precede that explicit command. Top-level `--help`, `-h`
+and `--version` never execute the default, and top-level help marks it.
+
+Aliases are command-local, one ASCII letter and validated against the resolved
+command schema. `-f` / `-f=false` are boolean forms; values accept `-n 100` and
+`-n=100`. Arrays accumulate across short and long forms. `-h` is reserved,
+bundles such as `-fn`, attached values such as `-n100`, `--no-f` and unknown
+short flags are rejected. Canonical `--no-follow` remains available.
+
+`positionals` replaces automatic schema-order selection only for the named
+command. An empty array disables argv positionals. Fields remain available as
+long/short options and stdin still fills the first required unset field with the
+same schema-aware coercion. Unknown, duplicate or boolean targets and a required
+positional after an optional/default positional fail when that command surface
+resolves. Native dispatch retains its lazy credential-free boundary; dynamic
+managed policies validate when their identity-dependent surface resolves.
 
 The advertised schema is never mutated — a CLI call validates against the exact
 same Zod schema an HTTP or MCP call does.
@@ -3921,10 +4006,12 @@ diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
 …) — override per app with `exitCodes`.
 
-Per-command help derives the positional form from the same schema order as the
-argv parser. For example, a required `action` and optional `profile` render as
+Per-command help derives the positional form from the same resolved policy as
+the argv parser. For example, a required `action` and optional `profile` render as
 `Usage: myapp skill <action> [profile] [--flags]`; the argument table also shows
 `<action> | --action` and `[profile] | --profile`. Boolean fields remain flags.
+Declared aliases render beside their canonical options, for example
+`-n, --lines`.
 
 ## `--wait` — background-friendly generation
 
@@ -6576,33 +6663,43 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
-## Unreleased migration: complete agent admission identity
+## Unreleased migration: normalized agent runtime persistence
 
-Custom `AgentRuntimeStore` adapters must persist and return the input and
-assistant identities associated with an idempotency key:
+`AgentRuntimeStoreDriver` no longer reads and rewrites a lifetime `AgentStoredState` JSON
+aggregate. Migrate that row and its recoverable/archive projections once:
+
+1. Copy `conversationId` and `version` into the bounded runtime head.
+2. Write every `AgentStoredState.runs[]` entry as one normalized run record.
+3. Write every `AgentStoredState.admissions[]` entry as one admission receipt and copy its
+   canonical input into that receipt.
+4. For terminal runs, retain the canonical assistant on the run record before deleting any old
+   history/archive rows.
+5. Replace the recoverable projection with an index over normalized run `state`.
+6. Cut the adapter over atomically; there is no compatibility driver or dual-write mode.
 
 ```ts
 // before
-return { outcome: 'duplicate', runId, snapshot }
+createAgentRuntimeStore({
+  state: { load, compareAndSwap },
+  history: { load, loadById, apply },
+  scanRecoverable,
+})
 
 // after
-return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+createAgentRuntimeStore({
+  head: { load, compareAndSwap },
+  runs: { load, loadByAssistantMessageId, loadMany, listActive, save },
+  admissions: { load, loadByInputMessageId, create },
+  history: { load, apply },
+  scanRecoverable,
+})
 ```
 
-Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
-its `AgentStoredState.admissions` record and transaction driver implement this
-contract automatically. `history.loadById()` must retain access to compacted
-admitted inputs so the framework can return the canonical record.
-
-`AgentRuntimeEvent` also adds a post-commit `admission` variant. Add it to any
-exhaustive publisher switch. Its `assistant` is either the pending placeholder
-for a new assignment or the canonical persisted assistant for a duplicate:
-
-```ts
-case 'admission':
-  await persistProductProjection(event.input, event.run, event.assistant)
-  break
-```
+`AgentRuntimeHeadSchema`, `AgentStoredRunSchema` and `AgentAdmissionReceiptSchema` replace
+`AgentStoredStateSchema` and `AgentAdmissionIdentitySchema`. Run
+`runAgentStoreConformance()` against the migrated adapter before switching production traffic.
+If an application implements `AgentRuntimeStore` directly, its duplicate result must also include
+the canonical `run` and the retained `assistant` for a terminal run.
 
 ## Released migration: 0.56.0
 
@@ -8039,13 +8136,15 @@ Server-only optional application runtime. See the
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAgentRuntime` | function | compose durable acceptance, stream loop, checkpoints, coordination, managed tools and terminal publication |
+| `createAgentRuntime` | function | compose durable acceptance, stream loop, checkpoints, coordination, managed tools and winner-only terminal publication; reconciles same-owner terminal/interrupt/head CAS races before releasing the lane |
 | `defineAgentProtocol` | function | declare and validate context, input metadata and canonical message parts |
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
-| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transactional state load/exact-version CAS, active-plus-archived history codec and bounded recoverable-run index scan |
-| `AgentStoredStateSchema` | schema | versioned runs and full idempotency admission identities without duplicated message history |
+| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history and indexed run recovery |
+| `AgentRuntimeHeadSchema` | schema | constant-size conversation identity plus monotonic runtime version |
+| `AgentStoredRunSchema` | schema | canonical normalized run with an optional retained terminal assistant |
+| `AgentAdmissionReceiptSchema` | schema | durable idempotency receipt with canonical input and assigned run/assistant identities |
 | `AgentHistoryMutationSchema` | schema | typed canonical message mutation applied inside the winning state transaction |
 | `RecoverAgentRunSchema` | schema | explicit abandon/requeue recovery decision; acquired runs require replay-safe evidence |
 | `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
@@ -8095,8 +8194,8 @@ Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssig
 `RequestRunInterrupt`, `RequestRunInterruptSchema`, `RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
-`AgentStoreNotFoundSchema`, `AgentAdmissionIdentity`, `AgentAdmissionIdentitySchema`,
-`AgentStoredState`, `AgentStoreCompareAndSwapResult`, `AgentHistoryMutation`,
+`AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,
+`AgentRuntimeHead`, `AgentStoredRun`, `AgentStoreCompareAndSwapResult`, `AgentHistoryMutation`,
 `AgentRecoverableDescriptor`, `AgentRecoverableDescriptorSchema`, `AgentRecoverablePage` and
 `AgentRecoverablePageSchema`.
 
@@ -8242,7 +8341,7 @@ payload.
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
-| `defineCliCommand` | function | define one typed CLI-only command with no fake managed-tool identity — [guide](../guide/cli.md#native-binary-commands) (also on `stitchkit/cli`) |
+| `defineCliCommand` | function | define one typed CLI-only command with optional post-validation `present` and successful `exitCode` policy — [guide](../guide/cli.md#native-binary-commands) (also on `stitchkit/cli`) |
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
 | `resolveMedia` | function | resolve a media reference for a tool result |
@@ -8299,11 +8398,12 @@ payload.
 | `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT' \| 'CLI'`; omission still means MCP+Agent only |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
-| `CliConfig` | _type_ | config for `createCli` |
+| `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection and command-scoped `optionAliases` / `positionals` policy |
+| `CliPresentationPolicyConfig` | _type_ | reusable default-command, short-alias and explicit-positional policy inherited by `CliConfig` |
 | `CliSurfaceSource` | _type_ | static managed surface or identity-dependent surface factory for `createCli` |
 | `CliCommandDefinition` | _type_ | Zod-first CLI-only command union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
-| `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema and validated handler result |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema, validated handler result and typed optional `present` / `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | void native command with no output schema |
 | `CliCommandContext` | _type_ | parsed native command input, global options and injected writers |
 | `CliWaitConfig` | _type_ | `--wait` polling config |
@@ -8567,16 +8667,17 @@ SDK nor the `ai` peer.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
-| `defineCliCommand` | function | define one Zod-typed CLI-only executable command |
+| `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
 | `pollUntilDone` | function | the generic `--wait` poller (advanced) |
 | `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
 | `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
-| `CliConfig` | _type_ | config for `createCli` |
+| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `optionAliases` and `positionals` define the shared command presentation policy |
+| `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
 | `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
 | `CliCommandDefinition` | _type_ | native command definition union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
-| `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
 | `CliCommandContext` | _type_ | parsed input, global options and stdout/stderr writers |
 | `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",