stitchkit 0.59.0 → 0.59.2

package/llms-full.txt

@@ -3570,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
 
@@ -3739,6 +3744,299 @@ coalescing, collision, stale checkpoint, replay safety, terminal race, compactio
 invariants against any fresh durable adapter.
 
 
+==============================================================================
+# Guide: Managed application kernel  (docs/guide/application-kernel.md)
+==============================================================================
+
+---
+title: Managed application kernel
+description: Compose process-local resources, schedules, readiness, drain and optional provider adapters without building a second job platform.
+type: architecture
+status: active
+created: 2026-08-23
+updated: 2026-08-23
+---
+
+# Managed application kernel
+
+Use `stitchkit/application` when several process-local resources must become
+ready and shut down as one application. Keep using the lower-level server and
+signal APIs when one managed server is already the complete lifecycle boundary.
+
+The neutral entrypoint is server-only and works on Bun and Node ≥ 22. It does
+not import provider SDKs.
+
+## Minimal composition
+
+```ts
+import {
+  createApplication,
+  createManagedSchedule,
+  defineManagedResource,
+  managedServerResource,
+} from 'stitchkit/application'
+import { bindProcessSignals } from 'stitchkit/server'
+
+const database = defineManagedResource({
+  id: 'database',
+  required: true,
+  start: async ({ signal, reportHealth }) => {
+    await db.connect({ signal })
+    reportHealth('healthy')
+  },
+  close: () => db.disconnect(),
+})
+
+const cleanup = createManagedSchedule({
+  id: 'cleanup',
+  dependsOn: ['database'],
+  everyMs: 60_000,
+  startAfterMs: 60_000,
+  overlap: { mode: 'skip' },
+  errorPolicy: 'continue',
+  run: ({ signal }) => removeExpiredRecords(signal),
+})
+
+const app = createApplication({
+  id: 'service',
+  resources: [
+    database,
+    managedServerResource({ id: 'http', server, dependsOn: ['database'] }),
+    cleanup,
+  ],
+})
+
+const signals = bindProcessSignals(app, {
+  shutdown: { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
+  onComplete: (result) => {
+    process.exitCode = result.outcome === 'clean' ? 0 : 1
+  },
+})
+
+await app.start()
+```
+
+The exact resource callbacks are typed by their public configuration. The
+important ownership rule is stable: the application creates and configures the
+database/server/provider objects; Stitchkit orders their process-local
+lifecycle.
+
+## Resource authoring
+
+Give every resource a stable, bounded ID and list its dependencies explicitly.
+The graph is validated before any start. Required resources may depend only on
+required resources; an optional integration cannot silently become a required
+dependency.
+
+Start and readiness are different. A connection can finish setup and return a
+ready handle. A poller can return a handle immediately, settle `ready` later,
+and keep a long-lived `completion` promise. Stitchkit observes both.
+
+Once Stitchkit invokes start/activation, cleanup is guaranteed to be attempted.
+Write `close` so it is safe when setup was partial:
+
+```ts
+let cacheClient: CacheClient | undefined
+
+const cache = defineManagedResource({
+  id: 'cache',
+  required: false,
+  start: async ({ signal, reportHealth }) => {
+    cacheClient = new CacheClient()
+    await cacheClient.connect(signal)
+    reportHealth('healthy')
+  },
+  close: async () => {
+    await cacheClient?.close()
+    cacheClient = undefined
+  },
+})
+```
+
+Invoking `start` makes the descriptor rollback-eligible immediately. Its
+`close` callback must therefore clean side effects even when `start` rejects
+before returning a runtime handle. The kernel calls cleanup once and continues
+cleaning other attempted resources even if one close fails.
+
+## Readiness and health
+
+`await app.start()` resolves only after every required resource is ready and
+every required post-ready activation has succeeded. Lifecycle `ready` is
+published before activation so schedules never arm during `starting`;
+application admission opens only after successful activation. Optional failure
+may retain lifecycle `ready`, but snapshot health is `degraded`, never
+`healthy`.
+
+Readiness is not hidden polling. A resource reports health changes through its
+lifecycle context; the application decides when a database/provider probe runs.
+A required long-lived completion that rejects after startup makes readiness
+false and health unhealthy. Stitchkit records the failure but does not restart
+the resource or process.
+
+`createApplicationHealthHandler` exposes the neutral lifecycle/health snapshot
+through a Fetch-compatible handler, suitable for a raw route on Bun or Node.
+Product-specific probes may be composed beside it; do not put secrets or raw
+provider failures in the response.
+
+## Admission and graceful shutdown
+
+Use the application operation lease for work that is not already counted by a
+managed resource:
+
+```ts
+const operation = app.admission.acquire()
+if (!operation) return Response.json({ error: 'unavailable' }, { status: 503 })
+
+try {
+  await performAcceptedWork()
+} finally {
+  operation.release()
+}
+```
+
+`release()` is idempotent. Admission and counter increment are atomic, so work
+cannot slip between the shutdown check and drain accounting.
+
+Shutdown performs one phase barrier at a time: stop admission everywhere,
+cancel future schedules, drain admitted work, then close in reverse stable
+topological order. Every hook shares the same grace deadline. Forced cleanup
+shares one force deadline. Repeated `shutdown()` calls return the cached promise;
+a repeated process signal forces that same chain.
+
+Do not add a second `process.on('SIGTERM')` handler around the application.
+`bindProcessSignals(app)` is the force/escalation owner. Exit code and hard-exit
+policy remain application/supervisor choices.
+
+## Managed schedules
+
+Schedules activate only after top-level readiness:
+
+```ts
+createManagedSchedule({
+  id: 'reconcile',
+  everyMs: 5_000,
+  startAfterMs: 0,
+  overlap: { mode: 'queue-one' },
+  errorPolicy: 'continue',
+  onError: (error) => internalLogger.error(error),
+  run: ({ signal }) => reconcile(signal),
+})
+```
+
+- `skip` ignores a due tick while one execution is active.
+- `queue-one` retains one successor; additional due ticks coalesce.
+- `parallel` requires `maxConcurrent`; overflow skips rather than creating a
+  hidden queue.
+
+The callback receives the application shutdown signal. Normal shutdown waits
+for admitted executions; force aborts the shared signal. There are no retries,
+cron/timezone rules, persisted cursors, backfill or cross-process locks. Put
+those semantics in a durable application scheduler when they are required.
+Schedule cadence stays monotonic, while status snapshots expose ISO wall-clock
+`capturedAt`, `changedAt` and next/last-run timestamps for portable observation.
+
+## Operational projection
+
+Declare aggregate activity stages, then update them with anonymous handles:
+
+```ts
+const generations = createActivityProjection({
+  id: 'generation',
+  stages: ['queued', 'running', 'finalizing'],
+})
+
+const activity = generations.open('queued', 'queued')
+generations.transition(activity, { stage: 'running', state: 'active' })
+generations.transition(activity, { stage: 'finalizing', state: 'active' })
+generations.complete(activity)
+```
+
+Item identity is deliberately absent from the snapshot. Observers receive
+aggregate counts with application identity, process epoch, revision and
+timestamps. Calling a terminal method twice does not double-count.
+
+```ts
+const sink = createApplicationSnapshotSink({
+  write: (snapshot) => publishOperationalSnapshot(snapshot),
+})
+
+const unsubscribe = generations.subscribe((snapshot) => {
+  sink.publish(snapshot)
+})
+
+// During application cleanup:
+unsubscribe()
+await sink.close()
+```
+
+The sink replays the current absolute value and coalesces obsolete pending
+revisions behind a slow write. Sink failure is observable but cannot fail the
+application operation that changed the projection.
+
+## Optional grammY adapter
+
+Install grammY only in an application that imports the adapter:
+
+```ts
+import { Bot } from 'grammy'
+import {
+  createGrammyWebhookResource,
+  grammyPollingResource,
+} from 'stitchkit/application/grammy'
+```
+
+For simple long polling, pass an already-configured bot:
+
+```ts
+const bot = new Bot(env.BOT_TOKEN)
+bot.command('start', (ctx) => ctx.reply('Hello'))
+bot.catch(({ error }) => internalLogger.error(error))
+
+const telegram = grammyPollingResource({
+  id: 'telegram',
+  bot,
+  required: true,
+})
+```
+
+Readiness follows grammY's `onStart`. Shutdown calls `bot.stop()` once and then
+awaits the retained `bot.start()` promise, because grammY documents that
+`stop()` alone does not wait for middleware completion.
+
+For webhook ingress, `createGrammyWebhookResource` wraps provider-owned update
+handling with admission and drain. The application still mounts the HTTP route,
+verifies/configures its webhook and chooses the grammY framework adapter. An
+update accepted before shutdown may finish; a later update is rejected.
+
+The adapter never reads the token/env, installs commands, changes `bot.catch`,
+chooses retry plugins, drops pending updates, sends outbound messages or stores
+updates. A durable inbox/retry worker remains an application component, not a
+mode of this adapter.
+
+## What disappears from an application
+
+A typical small service can replace roughly 120–220 lines of generic signal,
+timer, admission and close bookkeeping with resource declarations. A larger
+multi-resource service commonly carries 250–450 generic lifecycle lines plus
+15–30 lines for each periodic timer. These are directional review estimates,
+not an API guarantee.
+
+The responsibility change is more important than line count:
+
+| Before | After |
+|---|---|
+| hand-written phase enum and readiness waiters | `createApplication` snapshot |
+| `process.on` signal loop and escalation | `bindProcessSignals(app)` |
+| interval/timeout handles and overlap flag | `createManagedSchedule` |
+| global in-flight counter and drain waiter set | application operation leases |
+| manual stop/close fan-out | resource graph + bounded shutdown |
+| progress delta events | absolute activity projection |
+
+Durable job tables, lifecycle journals/outboxes, provider inboxes and business
+retry rules do **not** disappear. They were never process-local glue and remain
+application-owned.
+
+
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
 ==============================================================================
@@ -3879,6 +4177,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
@@ -3905,9 +4229,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.
@@ -3932,10 +4299,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
 
@@ -8053,6 +8422,92 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 ---
 
+## `stitchkit/application`
+
+Server-only process-local application composition. See the
+[application kernel guide](../guide/application-kernel.md) and
+[architecture](../architecture/application-kernel.md).
+
+### Kernel and resources
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createApplication` | function | compose a validated resource DAG into one non-restartable startup, readiness, admission and shutdown state machine |
+| `defineManagedResource` | function | retain the exact typed resource declaration; every invoked start is rollback-eligible |
+| `managedServerResource` | function | adapt an existing managed server without copying its HTTP/WebSocket shutdown machine |
+| `createApplicationHealthHandler` | function | build a Fetch-clean liveness or readiness response from the sanitized application snapshot |
+| `ApplicationAdmissionError` | class | stable `APPLICATION_NOT_ACCEPTING` rejection from `admission.run(...)` |
+| `ApplicationConfig` / `ApplicationHandle` | _type_ | application declaration and its start/snapshot/subscription/admission/shutdown handle |
+| `ApplicationAdmission` / `ApplicationOperationLease` | _type_ | atomic process-local admission and idempotent release primitive |
+| `ManagedResource` / `ManagedResourceContext` / `ManagedResourceStartResult` | _type_ | resource lifecycle callbacks, shared deadlines, health reporting and separate readiness/completion promises |
+| `ManagedServerResourceConfig` | _type_ | existing managed server, stable ID, dependencies and policy for `managedServerResource` |
+| `ApplicationHealthHandlerOptions` / `ApplicationHealthHandlerOptionsSchema` | _type_ / schema | liveness/readiness selection and sanitized `Retry-After` policy |
+
+### Managed schedules
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createManagedSchedule` | function | fixed-rate process-local timer that activates after top-level readiness and participates in drain |
+| `ManagedScheduleOverlapSchema` / `ManagedScheduleOverlap` | schema / _type_ | `skip`, `queue-one` or bounded `parallel` overlap policy |
+| `ManagedScheduleErrorPolicySchema` / `ManagedScheduleErrorPolicy` | schema / _type_ | `continue` or `stop-schedule` after an observed callback failure |
+| `ManagedScheduleDescriptorSchema` / `ManagedScheduleDescriptor` | schema / _type_ | immutable public schedule identity and cadence policy |
+| `ManagedScheduleStatusSchema` / `ManagedScheduleStatus` | schema / _type_ | absolute schedule state, revision, counters and timestamps |
+
+Schedule authoring additionally exports `ManagedSchedule`, `ManagedScheduleConfig`,
+`ManagedScheduleRunContext`, `ManagedScheduleClock` and `ManagedScheduleTimer`.
+The clock exposes monotonic cadence/deadline arithmetic and a wall-clock projection for portable
+status timestamps; it is a deterministic test boundary, not a durable scheduler.
+
+### Application and activity projection
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createActivityProjection` | function | aggregate anonymous process-local activity into declared bounded stages and absolute snapshots |
+| `createApplicationSnapshotSink` | function | latest-value delivery with one write in flight and one replaceable pending revision |
+| `applicationLifecycleEvent` | function | project a sanitized lifecycle fact from a canonical application snapshot |
+| `createApplicationEventSink` | function | bounded failure-isolated lifecycle-event delivery; events are not canonical state |
+| `ActivitySnapshotSchema` / `ActivitySnapshot` | schema / _type_ | epoch, monotonic revision, timestamps, declared stages and aggregate counts |
+| `ApplicationSnapshotSinkStatusSchema` / `ApplicationSnapshotSinkStatus` | schema / _type_ | immutable latest-value sink delivery and coalescing counters |
+| `ApplicationLifecycleEventSchema` / `ApplicationLifecycleEvent` | schema / _type_ | sanitized operator-facing application lifecycle fact |
+
+Activity authoring additionally exports `ActivityId`, `ActivityIdSchema`,
+`ActivityStageId`, `ActivityStageIdSchema`, `ActivityStageSnapshot`,
+`ActivityStageSnapshotSchema`, `ActivityLiveState`, `ActivityLiveStateSchema`,
+`ActivityProjection`, `ActivityProjectionConfig`,
+`ActivityProjectionSubscriberError`, `ActivityToken` and `ActivityTransition`.
+Latest-value delivery exports `ApplicationSnapshotSink`,
+`ApplicationSnapshotSinkConfig`, `ApplicationSnapshotSinkError` and
+`RevisionedApplicationSnapshot`; event delivery exports `ApplicationEventSink`
+and `ApplicationEventSinkConfig`.
+
+### Canonical application records
+
+The entrypoint exports each Zod schema beside its inferred type:
+`ApplicationIdSchema` / `ApplicationId`, `ApplicationLifecycleSchema` /
+`ApplicationLifecycle`, `ApplicationHealthSchema` / `ApplicationHealth`,
+`ManagedResourceStateSchema` / `ManagedResourceState`,
+`ApplicationAdmissionSnapshotSchema` / `ApplicationAdmissionSnapshot`,
+`ManagedResourceSnapshotSchema` / `ManagedResourceSnapshot`,
+`ApplicationSnapshotSchema` / `ApplicationSnapshot`,
+`ApplicationResourceShutdownSchema` / `ApplicationResourceShutdown`, and
+`ApplicationShutdownResultSchema` / `ApplicationShutdownResult`.
+
+## `stitchkit/application/grammy`
+
+Isolated optional-peer lifecycle adapters. Importing `stitchkit/application`
+does not resolve grammY.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `grammyPollingResource` | function | adapt an injected bot's long polling with distinct `onStart` readiness, observed completion and one stop chain |
+| `createGrammyWebhookResource` | function | return a managed resource plus admission-guarded `handleUpdate`; HTTP hosting and webhook registration stay application-owned |
+| `GrammyWebhookUnavailableError` | class | stable `GRAMMY_WEBHOOK_NOT_ACCEPTING` rejection after webhook admission closes |
+| `GrammyPollingResourceConfig` | _type_ | injected bot, polling options, resource graph policy and isolated error observer |
+| `GrammyWebhookResourceConfig` / `GrammyWebhookResource` | _type_ | injected webhook bot declaration and `{ resource, handleUpdate }` handle |
+| `GrammyUpdate` | _type_ | exact update input inferred from the injected grammY bot context |
+
+---
+
 ## `stitchkit/agent-runtime`
 
 Server-only optional application runtime. See the
@@ -8060,7 +8515,7 @@ 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 |
@@ -8265,7 +8720,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 |
@@ -8322,11 +8777,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 |
@@ -8590,16 +9046,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/llms.txt

@@ -11,6 +11,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
 - [Agent application runtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/agent-runtime.md): optional durable history, prompt/model composition, stream loop, coordination, fencing and events
+- [Managed application kernel](https://github.com/max-listov/stitchkit/blob/master/docs/guide/application-kernel.md): process-local resources, readiness, admission, schedules, projections and optional provider adapters
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program
 - [Realtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/realtime.md): Socket.IO server/client wrappers, handshake auth, the cache bridge, a raw WebSocket lane
 - [Auth & errors](https://github.com/max-listov/stitchkit/blob/master/docs/guide/auth-and-errors.md): scopes, createAuthHook, JWT/cookies, the AppError model, the stitch error-code registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.59.0",
+  "version": "0.59.2",
   "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",
@@ -84,6 +84,14 @@
       "types": "./dist/agent-runtime-openrouter.d.ts",
       "import": "./dist/agent-runtime-openrouter.js"
     },
+    "./application": {
+      "types": "./dist/application.d.ts",
+      "import": "./dist/application.js"
+    },
+    "./application/grammy": {
+      "types": "./dist/application-grammy.d.ts",
+      "import": "./dist/application-grammy.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
@@ -103,7 +111,7 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
@@ -124,6 +132,7 @@
     "@socket.io/component-emitter": "^3.1.2",
     "@tanstack/react-query": ">=5",
     "ai": "^7.0.0",
+    "grammy": "^1.45.1",
     "react": ">=18",
     "react-query-kit": "^3.3.3",
     "socket.io": "^4.8.3",
@@ -156,6 +165,9 @@
     "ai": {
       "optional": true
     },
+    "grammy": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
@@ -188,6 +200,7 @@
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
     "ai": "^7.0.65",
+    "grammy": "^1.45.1",
     "react": "^19.2.8",
     "react-query-kit": "^3.3.4",
     "socket.io": "^4.8.3",