@happyvertical/smrt-playbooks 0.44.0

package/AGENTS.md

@@ -0,0 +1,174 @@
+# smrt-playbooks
+
+Layered playbook registry, app/tenant overrides, and plan resolution. A
+playbook is a named, described, layered sequence of steps an agent follows;
+browser agents, in-app agents, the Node MCP server, and the CLI all follow the
+same resolved plan. Fourth instance of the `smrt-prompts` layered-override
+pattern — keep it consistent with `prompts`, `languages`, and `features`.
+
+## Core pieces
+
+- `definePlaybook()` registers code defaults in a global process registry
+  (`globalThis.__smrtPlaybookRegistry`), so a package-bundled playbook resolves
+  with no application registration
+- `resolvePlaybook()` merges the layers and returns a `PlaybookResolution`
+- `PlaybookOverride` (`_smrt_playbook_overrides`) stores partial app-level and
+  tenant-level overrides with write-time validation
+- `PlaybookOverrideCollection` exposes the standard SmrtCollection CRUD surface
+
+## Resolution layers (priority low → high)
+
+1. Code default — `definePlaybook({ key, title, description, steps })`
+2. File/config override — `getPackageConfig<PlaybookPackageConfig>('playbooks', defaults)`
+3. App-level stored override — `PlaybookOverride` row with `tenantId = null`
+4. Tenant-level stored override — `PlaybookOverride` row with the current tenant
+5. Runtime override — passed to `resolvePlaybook(key, { override })`
+
+Inheritance is field-by-field: a stored column is nullable, and `null` means
+"use the lower layer".
+
+## Script semantics
+
+A playbook resolves to a plan the agent executes step by step. **It never
+executes as a unit** (epic #2585 invariant 4), so it is never an authority
+boundary and adds no new security object to review. Each step is authorized
+independently — at the REST boundary in the browser, or by
+`PrincipalRun.assertToolAllowed()` server-side. Nothing in this package
+executes a step, and there is deliberately no executor export.
+
+Playbooks are consequently never atomic and have no compensation.
+`onStepFailure` (`'abort'` | `'continue'`) is the whole of the contract for
+what an agent does when step 3 of 5 fails.
+
+## Steps
+
+Exactly two kinds in v1, and playbooks cannot nest:
+
+- `{ kind: 'operation', model: '@happyvertical/smrt-commerce:Order', action: 'submit' }`
+  — the qualified pair already used by STI discriminators and
+  `@crossPackageRef`. **Never a generated tool name**: that is derived from
+  model, action, and namespace, and would silently orphan stored tenant
+  overrides on a namespace change.
+- `{ kind: 'intent', id }` — a view intent named by its declared #2588
+  identity. Valid only where a surface is mounted.
+
+A step referencing another playbook is rejected in `normalizeSteps()` at
+definition time.
+
+### Classification is inherited, never self-declared
+
+A step never classifies itself. `resolvePlaybook()` takes a
+`classifier` (and, for intents, an `intents` registry) supplied by the host,
+which returns the `CapabilityDeclaration` emitted for the referenced operation
+by `@happyvertical/smrt-types`. Anything undeclared resolves fail-closed to
+`{ effect: 'destructive', idempotent: false, openWorld: true }`. The
+vocabulary itself is older and lower and shared with model tools — it lives in
+`smrt-types`, not here (owning it here would close a
+core → playbooks → core cycle).
+
+## Plane validity
+
+A playbook declares `planes: readonly ('browser' | 'server')[]`. Resolution for
+a caller on an undeclared plane fails closed with reason
+`'plane-not-declared'`.
+
+- Operation-only playbooks default to both planes.
+- A playbook containing a view-intent step defaults to `['browser']`. Server
+  validity rides the shipped #2446 browser command/ack bridge, which lets a
+  server-side agent drive mounted surfaces with acknowledgement — it must be
+  **declared explicitly**, never assumed.
+- The same default applies one level down: a `PlaybookIntentRecord` that
+  declares no `planes` is browser-only, so server validity must be declared at
+  **both** the playbook and the intent. Silence from the intent registry never
+  widens a plane (`'intent-plane-not-declared'`).
+
+The `#2588` intent registry does not exist yet, so an intent step with no
+`intents` resolver supplied fails closed with
+`'intent-registry-unavailable'`. That resolver is the seam #2588 wires into.
+
+## Editability
+
+`editable` defaults **all-false**, matching `normalizeEditableConfig` in
+`smrt-prompts`. Every stored column has a flag — `title`, `description`,
+`planes`, `onStepFailure`, `enabled`, `metadata` — and `save()` rejects a
+non-null value for any field the definition has not opted in. `onStepFailure`
+is gated like the rest: flipping a locked playbook from `'abort'` to
+`'continue'` would change what an agent does after a failed prerequisite.
+
+`steps` is **structurally** non-editable, not merely defaulted false:
+
+- `PlaybookEditableConfig` has no `steps` key, and marking one throws at
+  definition time
+- `_smrt_playbook_overrides` has **no `steps` column**, so no write of any kind
+  has anywhere to put a step list
+- `PlaybookOverride.save()` rejects a `steps` property assigned through the
+  untyped option bag rather than dropping it silently
+- `normalizePlaybookLayer()` throws on a `steps` key from the config or runtime
+  layer
+- the resolver reads steps only from `PlaybookRegistry`
+
+The reason is not escalation — under the script model a tenant cannot escalate,
+since every step is authorized independently regardless of who wrote the list.
+It is that an agent announcing "checking out your cart" while an overridden
+step list does something else is a description-behavior mismatch.
+
+Enablement overrides are one-directional: a layer may disable, never re-enable
+what a lower layer disabled. Enforced in `mergePlaybookLayers()` (`enabled &&
+layer.enabled`) and rejected at `save()` with a specific message. Plane lists
+narrow the same way.
+
+## Caching
+
+Resolutions are cached per `(key, tenantId, db)` with a TTL. The cache is
+invalidated on `PlaybookOverride.save()` and `.delete()`; an app-level write
+(`tenantId = null`) clears every tenant's entry for that key, because each
+tenant inherits from it. Use `clearPlaybookCache()` in tests.
+
+A monotonic per-`(db, key)` invalidation generation closes the read-racing-a-
+write window; see the Gotchas entry below before touching `cache.ts`.
+
+## Gotchas
+
+- **`context` carries the tenant scope.** `save()` sets
+  `this.context = this.tenantId ?? '__app__'` and `conflictColumns` is
+  `['key', 'context']`. `tenantId` is nullable, and a unique index over it
+  would let multiple NULL rows coexist on PostgreSQL and DuckDB. The `context`
+  trick (from `smrt-languages`) is what makes the same upsert correct on all
+  three dialects — do not "simplify" it to `['key', 'tenantId']`.
+- **Identity changes need the delete-then-insert dance.** Changing `key` or
+  `tenantId` on an existing row changes the conflict identity, so a plain
+  `super.save()` writes the old primary key under a new one. Same handling as
+  `PromptOverride` / `LanguageOverride`: a transaction where the driver has
+  one, otherwise a staged replacement row deleted only after the new row is
+  durable.
+- **JSON fields are stored as strings.** `planes` and `metadata` are text
+  columns with guarded `getPlanes()` / `setPlanes()` / `getMetadata()` /
+  `setMetadata()` helpers that swallow parse errors. Never override
+  `toJSON()`; extend serialization through `transformJSON()`.
+- **`resolvePlaybook()` returns a result, it does not throw for policy.**
+  Unknown key, disabled, wrong plane, and unresolvable intents all come back as
+  `{ ok: false, reason, message }`. It *does* throw for programming errors —
+  notably a `steps` key on an override layer.
+- **The cache carries an invalidation generation, and this is where it
+  diverges from `smrt-prompts`.** A resolution captures
+  `getPlaybookCacheGeneration(key, db)` before its asynchronous layer loads and
+  hands it back to `setCachedPlaybookBase()`; a concurrent `save()` / `delete()`
+  bumps the generation, and the in-flight resolution is then refused the cache
+  write instead of repopulating the key it just invalidated with the pre-write
+  value. Without it, "a stale entry is never served after a write" held only
+  until a read raced a write, and then failed for the full 30s TTL. Generations
+  are tracked per `(db, key)`, not per tenant, because an app-level row is
+  inherited by every tenant. `clearPlaybookCache()` bumps rather than resets
+  them, so a resolution that started before the clear cannot write back either.
+  `smrt-prompts` and `smrt-languages` still carry the unguarded version of this
+  race; fixing them is separate work.
+- **Restart vitest after adding a decorated class**; the manifest is generated
+  at startup.
+
+## Related
+
+- `@happyvertical/smrt-prompts` — the pattern this package clones
+- `@happyvertical/smrt-languages` — source of the `context` column convention
+- `@happyvertical/smrt-features` — parallel package for feature flags
+- Epic #2585 — declared agent surface; #2587 capability vocabulary,
+  #2588 view intents, #2590 preflight, #2591 manifest emission

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @happyvertical/smrt-playbooks
+
+Layered playbook definitions, tenant-aware overrides, and plan resolution for
+s-m-r-t agents.
+
+A playbook is a named, described sequence of steps an agent follows. It gives a
+multi-step intent — "check out this cart" — a home that is neither a custom
+model action nor a view intent, and browser agents, in-app agents, the Node MCP
+server, and the CLI all follow the same resolved plan.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-playbooks
+```
+
+## Quick start
+
+```typescript
+import { definePlaybook, resolvePlaybook } from '@happyvertical/smrt-playbooks';
+
+// 1. Register a playbook's defaults at startup
+definePlaybook({
+  key: 'commerce.cart.checkout',
+  title: 'Check out this cart',
+  description: 'Submits the order and captures payment.',
+  steps: [
+    {
+      kind: 'operation',
+      model: '@happyvertical/smrt-commerce:Order',
+      action: 'submit',
+    },
+    {
+      kind: 'operation',
+      model: '@happyvertical/smrt-commerce:Payment',
+      action: 'capture',
+    },
+  ],
+  onStepFailure: 'abort',
+});
+
+// 2. Resolve a plan for a caller on a plane
+const resolution = await resolvePlaybook('commerce.cart.checkout', {
+  db,
+  plane: 'server',
+});
+
+if (!resolution.ok) {
+  // Fails closed with a specific reason: unknown-playbook, disabled,
+  // plane-not-declared, intent-registry-unavailable, unknown-intent.
+  throw new Error(resolution.message);
+}
+
+for (const step of resolution.plan.steps) {
+  // The agent executes each step itself; this package never does.
+  // step.classification is inherited from the referenced operation.
+}
+```
+
+## What this package provides
+
+- **`definePlaybook()`** — code-first playbook registration in a global process
+  registry, so a package ships its own playbooks
+- **`resolvePlaybook()`** — layered resolution: code default → config override →
+  stored app override → stored tenant override → runtime override
+- **`PlaybookOverride`** — CRUD model for app-level and tenant-level playbook
+  settings, stored in `_smrt_playbook_overrides`
+- **Plane validity** — a playbook declares `browser`, `server`, or both, and
+  resolution on an undeclared plane fails closed
+- **TTL cache** keyed by `(key, tenantId)`, invalidated on override save/delete
+
+## Guarantees
+
+- **A playbook is a script, never a call.** Resolution returns a plan; nothing
+  here executes a step. A playbook is therefore never an authority boundary —
+  each step is authorized independently where it runs.
+- **Step lists are never editable.** No override layer, including a direct
+  model write, can change a playbook's steps. An agent's description of what it
+  is about to do always matches the steps it will follow.
+- **Enablement narrows only.** A tenant may disable a playbook; it can never
+  enable one a lower layer disabled.
+- **Undeclared classification fails closed** to
+  `{ effect: 'destructive', idempotent: false, openWorld: true }`. Steps never
+  classify themselves; classification is inherited from the referenced
+  operation.
+
+## Documentation
+
+- See [`AGENTS.md`](./AGENTS.md) for package-internal patterns
+- See [`docs/content/standards.md`](../../docs/content/standards.md) for
+  monorepo conventions
+- See related: [`@happyvertical/smrt-prompts`](../prompts) (the layered-override
+  pattern this package mirrors),
+  [`@happyvertical/smrt-languages`](../languages),
+  [`@happyvertical/smrt-features`](../features)

package/dist/index.d.ts

@@ -0,0 +1,345 @@
+import { CapabilityClassification } from '@happyvertical/smrt-types';
+import { CapabilityDeclaration } from '@happyvertical/smrt-types';
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+export declare function clearPlaybookCache(): void;
+
+/**
+ * Registers a code-default playbook. Packages call this at import time so a
+ * bundled playbook resolves without any application registration.
+ */
+export declare function definePlaybook(input: PlaybookDefinitionInput): PlaybookDefinition;
+
+/**
+ * Fail-closed capability classification, per epic #2585 invariant 3. Applied
+ * whenever the host cannot tell us how a referenced operation is classified.
+ */
+export declare const FAIL_CLOSED_CLASSIFICATION: CapabilityClassification;
+
+export declare function getPlaybookCacheTtlMs(): number;
+
+export declare function normalizeEditableConfig(editable?: Partial<PlaybookEditableConfig>): PlaybookEditableConfig;
+
+/* Excluded from this release type: PACKAGE_VERSION_INITIALIZED */
+
+export declare const PLAYBOOK_PLANES: readonly PlaybookPlane[];
+
+export declare interface PlaybookAcceptance {
+    ok: true;
+    plan: PlaybookPlan;
+}
+
+export declare interface PlaybookCacheValue {
+    key: string;
+    title: string;
+    description: string;
+    planes: readonly PlaybookPlane[];
+    onStepFailure: PlaybookFailurePolicy;
+    enabled: boolean;
+    metadata: PlaybookMetadata;
+}
+
+/**
+ * A partial override from any layer above the code default. There is no
+ * `steps` key, and supplying one is rejected rather than ignored.
+ */
+export declare interface PlaybookConfigOverrideInput {
+    title?: string | null;
+    description?: string | null;
+    planes?: readonly PlaybookPlane[] | null;
+    onStepFailure?: PlaybookFailurePolicy | null;
+    enabled?: boolean | null;
+    metadata?: PlaybookMetadata | null;
+    [key: string]: unknown;
+}
+
+export declare interface PlaybookDefinition {
+    key: string;
+    title: string;
+    description: string;
+    steps: readonly PlaybookStep[];
+    planes: readonly PlaybookPlane[];
+    onStepFailure: PlaybookFailurePolicy;
+    enabled: boolean;
+    metadata: PlaybookMetadata;
+    editable: PlaybookEditableConfig;
+}
+
+export declare interface PlaybookDefinitionInput {
+    key: string;
+    title: string;
+    description: string;
+    steps: readonly PlaybookStep[];
+    /**
+     * Planes this playbook is valid on. Defaults to both planes when every step
+     * is a model operation, and to `['browser']` when any step is a view intent
+     * — server validity for an intent-bearing playbook rides the #2446 browser
+     * command/ack bridge and must be declared explicitly.
+     */
+    planes?: readonly PlaybookPlane[];
+    onStepFailure?: PlaybookFailurePolicy;
+    enabled?: boolean;
+    metadata?: PlaybookMetadata | null;
+    editable?: Partial<PlaybookEditableConfig>;
+}
+
+/**
+ * Fields a stored override layer may change when the definition opts in.
+ *
+ * `steps` is deliberately absent: it is structurally non-editable, not merely
+ * defaulted false. No override layer can carry a step list at all.
+ */
+export declare interface PlaybookEditableConfig {
+    title: boolean;
+    description: boolean;
+    planes: boolean;
+    onStepFailure: boolean;
+    enabled: boolean;
+    metadata: boolean;
+}
+
+/**
+ * What an agent does when a step fails partway through a plan. Playbooks are
+ * scripts, never atomic units, so there is no compensation: the definition
+ * says only whether the remainder of the plan is abandoned.
+ */
+export declare type PlaybookFailurePolicy = 'abort' | 'continue';
+
+/**
+ * Record returned by an intent registry for a declared view intent.
+ *
+ * Seam for #2588: until an intent registry exists, no resolver is supplied and
+ * an intent step fails resolution closed.
+ */
+export declare interface PlaybookIntentRecord {
+    id: string;
+    classification?: CapabilityDeclaration | null;
+    planes?: readonly PlaybookPlane[] | null;
+}
+
+/** Seam for #2588. */
+export declare type PlaybookIntentResolver = (id: string) => PlaybookIntentRecord | null | undefined;
+
+/**
+ * A step naming a declared view intent by its identity (#2588). Valid only
+ * where a surface is mounted.
+ */
+export declare interface PlaybookIntentStep {
+    kind: 'intent';
+    /** Declared intent identity from the #2588 intent registry. */
+    id: string;
+    label?: string;
+    description?: string;
+    optional?: boolean;
+}
+
+/** One normalized override layer. `null` means "clear"; `undefined` means "inherit". */
+export declare interface PlaybookLayer {
+    title?: string | null;
+    description?: string | null;
+    planes?: readonly PlaybookPlane[] | null;
+    onStepFailure?: PlaybookFailurePolicy | null;
+    enabled?: boolean | null;
+    metadata?: PlaybookMetadata | null;
+}
+
+export declare type PlaybookMetadata = Record<string, unknown>;
+
+/**
+ * Resolves the capability classification of a referenced model operation.
+ *
+ * Playbooks never classify a step themselves. A host that knows the emitted
+ * build-time classification (core's `tool-schema.ts` output, or the runtime
+ * manifest) supplies it here; anything it does not know resolves fail-closed
+ * to `{ effect: 'destructive', idempotent: false, openWorld: true }`.
+ */
+export declare type PlaybookOperationClassifier = (step: PlaybookOperationStep) => CapabilityDeclaration | null | undefined;
+
+/**
+ * A step naming a model operation by qualified pair — the same qualified
+ * form STI discriminators and `@crossPackageRef` already use. Never a
+ * generated tool name: that is derived from model, action, and namespace and
+ * would silently orphan stored tenant overrides on a namespace change.
+ *
+ * The step never classifies itself; classification is inherited from the
+ * referenced operation (see {@link PlaybookOperationClassifier}).
+ */
+export declare interface PlaybookOperationStep {
+    kind: 'operation';
+    /** Qualified model name, e.g. `@happyvertical/smrt-commerce:Order`. */
+    model: string;
+    /** Operation name exposed by the model's `@smrt({ api })` surface. */
+    action: string;
+    /** Human-facing label for the agent's narration of this step. */
+    label?: string;
+    /** Longer human-facing description of the step. */
+    description?: string;
+    /** When true, an agent may skip this step without abandoning the plan. */
+    optional?: boolean;
+}
+
+/**
+ * Stored app-level (`tenantId = null`) and tenant-level playbook overrides.
+ *
+ * There is deliberately **no `steps` column**. `steps` is structurally
+ * non-editable: an override layer has nowhere to put a step list, and
+ * assigning one is rejected in `save()` rather than silently dropped. That is
+ * the description-behavior guarantee from epic #2585 — an agent announcing
+ * "checking out your cart" must not be following a rewritten script.
+ */
+export declare class PlaybookOverride extends SmrtObject {
+    key: string;
+    tenantId: string | null;
+    title: string | null;
+    description: string | null;
+    /** JSON array of plane names; null inherits the lower layer. */
+    planes: string | null;
+    onStepFailure: string | null;
+    /** Tri-state: null inherits, false disables. True can never widen. */
+    enabled: boolean | null;
+    /** JSON object; stored as a string with guarded get/set helpers. */
+    metadata: string | null;
+    constructor(options?: PlaybookOverrideOptions);
+    getMetadata(): PlaybookMetadata;
+    setMetadata(metadata: PlaybookMetadata | null): void;
+    getPlanes(): readonly PlaybookPlane[] | null;
+    setPlanes(planes: readonly PlaybookPlane[] | null): void;
+    toPlaybookLayer(): PlaybookLayer;
+    save(): Promise<this>;
+    private saveAfterIdentityChange;
+    private saveAfterIdentityChangeInTransaction;
+    private saveAfterIdentityChangeWithDeferredDelete;
+    delete(): Promise<void>;
+    private validatePlaybookOverride;
+    private getLowerPrecedenceLayers;
+    private normalizeForPersistence;
+    private getPersistedIdentity;
+}
+
+export declare class PlaybookOverrideCollection extends SmrtCollection<PlaybookOverride> {
+    static readonly _itemClass: typeof PlaybookOverride;
+    private excludeOverrideId;
+    getAppOverride(key: string, options?: {
+        excludeId?: string;
+    }): Promise<PlaybookOverride | null>;
+    getTenantOverride(key: string, tenantId: string, options?: {
+        excludeId?: string;
+    }): Promise<PlaybookOverride | null>;
+    getResolutionLayers(key: string, tenantId?: string | null, options?: {
+        excludeId?: string;
+    }): Promise<{
+        app: PlaybookOverride | null;
+        tenant: PlaybookOverride | null;
+    }>;
+}
+
+export declare interface PlaybookOverrideOptions extends SmrtObjectOptions, PlaybookOverrideOptions_2 {
+}
+
+declare interface PlaybookOverrideOptions_2 {
+    key?: string;
+    tenantId?: string | null;
+    title?: string | null;
+    description?: string | null;
+    planes?: string | readonly PlaybookPlane[] | null;
+    onStepFailure?: PlaybookFailurePolicy | null;
+    enabled?: boolean | null;
+    metadata?: string | PlaybookMetadata | null;
+}
+
+export declare interface PlaybookPackageConfig {
+    playbooks?: Record<string, PlaybookConfigOverrideInput>;
+    [key: string]: unknown;
+}
+
+/**
+ * The output of resolution: a plan an agent follows step by step. Nothing in
+ * this package executes a step, and the plan is not an authority boundary —
+ * every step is authorized independently where it runs.
+ */
+export declare interface PlaybookPlan {
+    key: string;
+    title: string;
+    description: string;
+    plane: PlaybookPlane;
+    planes: readonly PlaybookPlane[];
+    onStepFailure: PlaybookFailurePolicy;
+    metadata: PlaybookMetadata;
+    steps: readonly PlaybookPlanStep[];
+}
+
+/**
+ * Execution planes a playbook can declare validity for.
+ *
+ * `browser` covers WebMCP / in-page agents driving mounted surfaces;
+ * `server` covers Node MCP, CLI, and in-app agents running under
+ * `executeAsPrincipal`.
+ */
+export declare type PlaybookPlane = 'browser' | 'server';
+
+/** One step of a resolved plan, with its inherited classification. */
+export declare interface PlaybookPlanStep {
+    index: number;
+    step: PlaybookStep;
+    classification: CapabilityClassification;
+    /** True when the classification is the fail-closed default. */
+    classificationDeclared: boolean;
+}
+
+/**
+ * Global process registry of code-default playbooks, keyed by namespaced key.
+ *
+ * Held on `globalThis` so it survives HMR, mirroring `PromptRegistry`.
+ */
+export declare const PlaybookRegistry: {
+    register(input: PlaybookDefinitionInput): PlaybookDefinition;
+    get(key: string): PlaybookDefinition | undefined;
+    has(key: string): boolean;
+    getAll(): PlaybookDefinition[];
+    clear(): void;
+};
+
+export declare interface PlaybookRejection {
+    ok: false;
+    reason: PlaybookRejectionReason;
+    message: string;
+    key: string;
+    /** Index of the offending step, when the rejection is step-scoped. */
+    stepIndex?: number;
+}
+
+export declare type PlaybookRejectionReason = 'unknown-playbook' | 'disabled' | 'plane-not-declared' | 'intent-registry-unavailable' | 'unknown-intent' | 'intent-plane-not-declared';
+
+/** Resolution fails closed: every rejection carries a specific reason. */
+export declare type PlaybookResolution = PlaybookAcceptance | PlaybookRejection;
+
+/** A playbook step. Exactly two kinds exist in v1; playbooks cannot nest. */
+export declare type PlaybookStep = PlaybookOperationStep | PlaybookIntentStep;
+
+/**
+ * Resolves a playbook to a plan for a caller on a given plane.
+ *
+ * Returns a discriminated result rather than throwing: resolution fails closed
+ * and every rejection names a specific reason. Nothing here executes a step —
+ * the plan is followed step by step by the agent, and each step is authorized
+ * independently at the REST boundary or by `PrincipalRun.assertToolAllowed()`.
+ */
+export declare function resolvePlaybook(key: string, options?: ResolvePlaybookOptions): Promise<PlaybookResolution>;
+
+export declare interface ResolvePlaybookOptions {
+    db?: SmrtClassOptions['db'];
+    tenantId?: string | null;
+    /** Plane the calling agent runs on. Defaults to `'server'`. */
+    plane?: PlaybookPlane;
+    /** Highest-precedence layer, supplied per call. */
+    override?: PlaybookConfigOverrideInput;
+    /** Host-supplied classification source for model-operation steps. */
+    classifier?: PlaybookOperationClassifier;
+    /** Host-supplied intent registry (#2588). */
+    intents?: PlaybookIntentResolver;
+}
+
+export { }