@happyvertical/smrt-playbooks 0.44.0

package/dist/smrt-knowledge.json

@@ -0,0 +1,367 @@
+{
+  "schemaVersion": 1,
+  "sensitiveFieldsExcluded": true,
+  "generatedAt": "1970-01-01T00:00:00.000Z",
+  "packageName": "@happyvertical/smrt-playbooks",
+  "packageVersion": "0.44.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "8a46a95d6f2703a4455c1650d24d6e87dc8639e7a1571e2422c7a03b24144f58",
+    "packageJson": "33280f99cc18eb097a57756d77e767daec0b2fba6ab17ba56e1fe808714cafd4",
+    "agents": "7166afd02b405a200e1bd7a99eab2cb83f3fe12f700b5ce91a5ebfcdd7e1117a"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/smrt-config": "workspace:*",
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-types": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "24.13.2",
+    "typescript": "5.9.3",
+    "vite": "8.1.4",
+    "vitest": "4.1.10"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-config",
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-types",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/sql"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "PlaybookOverrideCollection",
+      "qualifiedName": "@happyvertical/smrt-playbooks:PlaybookOverrideCollection",
+      "collection": "playbookoverrides",
+      "tableName": "_smrt_playbook_overrides",
+      "packageName": "@happyvertical/smrt-playbooks",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getAppOverride",
+        "getResolutionLayers",
+        "getTenantOverride"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getAppOverride",
+          "async": true,
+          "params": [
+            "key: string",
+            "options?: object"
+          ],
+          "returns": "Promise<PlaybookOverride | null>"
+        },
+        {
+          "name": "getResolutionLayers",
+          "async": true,
+          "params": [
+            "key: string",
+            "tenantId?: string | null",
+            "options?: object"
+          ],
+          "returns": "Promise<object>"
+        },
+        {
+          "name": "getTenantOverride",
+          "async": true,
+          "params": [
+            "key: string",
+            "tenantId: string",
+            "options?: object"
+          ],
+          "returns": "Promise<PlaybookOverride | null>"
+        }
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "PlaybookOverride",
+      "qualifiedName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+      "collection": "playbookoverrides",
+      "tableName": "_smrt_playbook_overrides",
+      "packageName": "@happyvertical/smrt-playbooks",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "key",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "title",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "description",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "planes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "onStepFailure",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "enabled",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "delete",
+        "getMetadata",
+        "getPlanes",
+        "save",
+        "setMetadata",
+        "setPlanes",
+        "toPlaybookLayer"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "getMetadata",
+          "returns": "PlaybookMetadata"
+        },
+        {
+          "name": "getPlanes",
+          "returns": "null"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise"
+        },
+        {
+          "name": "setMetadata",
+          "params": [
+            "metadata: PlaybookMetadata | null"
+          ],
+          "returns": "void"
+        },
+        {
+          "name": "setPlanes",
+          "params": [
+            "planes: null"
+          ],
+          "returns": "void"
+        },
+        {
+          "name": "toPlaybookLayer",
+          "returns": "PlaybookLayer"
+        }
+      ],
+      "conflictColumns": [
+        "key",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "playbookoverrides.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+          "path": "/playbookoverrides",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "playbookoverrides.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+          "path": "/playbookoverrides/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "playbookoverrides.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+          "path": "/playbookoverrides",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "playbookoverrides.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+          "path": "/playbookoverrides/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "api",
+          "name": "playbookoverrides.delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+          "path": "/playbookoverrides/[id]",
+          "method": "DELETE"
+        },
+        {
+          "kind": "cli",
+          "name": "playbookoverride_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "playbookoverride_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "playbookoverride_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "playbookoverride_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "playbookoverride_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "playbookoverrides.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+      "path": "/playbookoverrides",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "playbookoverrides.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+      "path": "/playbookoverrides/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "playbookoverrides.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+      "path": "/playbookoverrides",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "playbookoverrides.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+      "path": "/playbookoverrides/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "api",
+      "name": "playbookoverrides.delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride",
+      "path": "/playbookoverrides/[id]",
+      "method": "DELETE"
+    },
+    {
+      "kind": "cli",
+      "name": "playbookoverride_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "playbookoverride_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "playbookoverride_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "playbookoverride_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "playbookoverride_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-playbooks:PlaybookOverride"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 2
+  },
+  "agentDoc": "# smrt-playbooks\n\nLayered playbook registry, app/tenant overrides, and plan resolution. A\nplaybook is a named, described, layered sequence of steps an agent follows;\nbrowser agents, in-app agents, the Node MCP server, and the CLI all follow the\nsame resolved plan. Fourth instance of the `smrt-prompts` layered-override\npattern — keep it consistent with `prompts`, `languages`, and `features`.\n\n## Core pieces\n\n- `definePlaybook()` registers code defaults in a global process registry\n  (`globalThis.__smrtPlaybookRegistry`), so a package-bundled playbook resolves\n  with no application registration\n- `resolvePlaybook()` merges the layers and returns a `PlaybookResolution`\n- `PlaybookOverride` (`_smrt_playbook_overrides`) stores partial app-level and\n  tenant-level overrides with write-time validation\n- `PlaybookOverrideCollection` exposes the standard SmrtCollection CRUD surface\n\n## Resolution layers (priority low → high)\n\n1. Code default — `definePlaybook({ key, title, description, steps })`\n2. File/config override — `getPackageConfig<PlaybookPackageConfig>('playbooks', defaults)`\n3. App-level stored override — `PlaybookOverride` row with `tenantId = null`\n4. Tenant-level stored override — `PlaybookOverride` row with the current tenant\n5. Runtime override — passed to `resolvePlaybook(key, { override })`\n\nInheritance is field-by-field: a stored column is nullable, and `null` means\n\"use the lower layer\".\n\n## Script semantics\n\nA playbook resolves to a plan the agent executes step by step. **It never\nexecutes as a unit** (epic #2585 invariant 4), so it is never an authority\nboundary and adds no new security object to review. Each step is authorized\nindependently — at the REST boundary in the browser, or by\n`PrincipalRun.assertToolAllowed()` server-side. Nothing in this package\nexecutes a step, and there is deliberately no executor export.\n\nPlaybooks are consequently never atomic and have no compensation.\n`onStepFailure` (`'abort'` | `'continue'`) is the whole of the contract for\nwhat an agent does when step 3 of 5 fails.\n\n## Steps\n\nExactly two kinds in v1, and playbooks cannot nest:\n\n- `{ kind: 'operation', model: '@happyvertical/smrt-commerce:Order', action: 'submit' }`\n  — the qualified pair already used by STI discriminators and\n  `@crossPackageRef`. **Never a generated tool name**: that is derived from\n  model, action, and namespace, and would silently orphan stored tenant\n  overrides on a namespace change.\n- `{ kind: 'intent', id }` — a view intent named by its declared #2588\n  identity. Valid only where a surface is mounted.\n\nA step referencing another playbook is rejected in `normalizeSteps()` at\ndefinition time.\n\n### Classification is inherited, never self-declared\n\nA step never classifies itself. `resolvePlaybook()` takes a\n`classifier` (and, for intents, an `intents` registry) supplied by the host,\nwhich returns the `CapabilityDeclaration` emitted for the referenced operation\nby `@happyvertical/smrt-types`. Anything undeclared resolves fail-closed to\n`{ effect: 'destructive', idempotent: false, openWorld: true }`. The\nvocabulary itself is older and lower and shared with model tools — it lives in\n`smrt-types`, not here (owning it here would close a\ncore → playbooks → core cycle).\n\n## Plane validity\n\nA playbook declares `planes: readonly ('browser' | 'server')[]`. Resolution for\na caller on an undeclared plane fails closed with reason\n`'plane-not-declared'`.\n\n- Operation-only playbooks default to both planes.\n- A playbook containing a view-intent step defaults to `['browser']`. Server\n  validity rides the shipped #2446 browser command/ack bridge, which lets a\n  server-side agent drive mounted surfaces with acknowledgement — it must be\n  **declared explicitly**, never assumed.\n- The same default applies one level down: a `PlaybookIntentRecord` that\n  declares no `planes` is browser-only, so server validity must be declared at\n  **both** the playbook and the intent. Silence from the intent registry never\n  widens a plane (`'intent-plane-not-declared'`).\n\nThe `#2588` intent registry does not exist yet, so an intent step with no\n`intents` resolver supplied fails closed with\n`'intent-registry-unavailable'`. That resolver is the seam #2588 wires into.\n\n## Editability\n\n`editable` defaults **all-false**, matching `normalizeEditableConfig` in\n`smrt-prompts`. Every stored column has a flag — `title`, `description`,\n`planes`, `onStepFailure`, `enabled`, `metadata` — and `save()` rejects a\nnon-null value for any field the definition has not opted in. `onStepFailure`\nis gated like the rest: flipping a locked playbook from `'abort'` to\n`'continue'` would change what an agent does after a failed prerequisite.\n\n`steps` is **structurally** non-editable, not merely defaulted false:\n\n- `PlaybookEditableConfig` has no `steps` key, and marking one throws at\n  definition time\n- `_smrt_playbook_overrides` has **no `steps` column**, so no write of any kind\n  has anywhere to put a step list\n- `PlaybookOverride.save()` rejects a `steps` property assigned through the\n  untyped option bag rather than dropping it silently\n- `normalizePlaybookLayer()` throws on a `steps` key from the config or runtime\n  layer\n- the resolver reads steps only from `PlaybookRegistry`\n\nThe reason is not escalation — under the script model a tenant cannot escalate,\nsince every step is authorized independently regardless of who wrote the list.\nIt is that an agent announcing \"checking out your cart\" while an overridden\nstep list does something else is a description-behavior mismatch.\n\nEnablement overrides are one-directional: a layer may disable, never re-enable\nwhat a lower layer disabled. Enforced in `mergePlaybookLayers()` (`enabled &&\nlayer.enabled`) and rejected at `save()` with a specific message. Plane lists\nnarrow the same way.\n\n## Caching\n\nResolutions are cached per `(key, tenantId, db)` with a TTL. The cache is\ninvalidated on `PlaybookOverride.save()` and `.delete()`; an app-level write\n(`tenantId = null`) clears every tenant's entry for that key, because each\ntenant inherits from it. Use `clearPlaybookCache()` in tests.\n\nA monotonic per-`(db, key)` invalidation generation closes the read-racing-a-\nwrite window; see the Gotchas entry below before touching `cache.ts`.\n\n## Gotchas\n\n- **`context` carries the tenant scope.** `save()` sets\n  `this.context = this.tenantId ?? '__app__'` and `conflictColumns` is\n  `['key', 'context']`. `tenantId` is nullable, and a unique index over it\n  would let multiple NULL rows coexist on PostgreSQL and DuckDB. The `context`\n  trick (from `smrt-languages`) is what makes the same upsert correct on all\n  three dialects — do not \"simplify\" it to `['key', 'tenantId']`.\n- **Identity changes need the delete-then-insert dance.** Changing `key` or\n  `tenantId` on an existing row changes the conflict identity, so a plain\n  `super.save()` writes the old primary key under a new one. Same handling as\n  `PromptOverride` / `LanguageOverride`: a transaction where the driver has\n  one, otherwise a staged replacement row deleted only after the new row is\n  durable.\n- **JSON fields are stored as strings.** `planes` and `metadata` are text\n  columns with guarded `getPlanes()` / `setPlanes()` / `getMetadata()` /\n  `setMetadata()` helpers that swallow parse errors. Never override\n  `toJSON()`; extend serialization through `transformJSON()`.\n- **`resolvePlaybook()` returns a result, it does not throw for policy.**\n  Unknown key, disabled, wrong plane, and unresolvable intents all come back as\n  `{ ok: false, reason, message }`. It *does* throw for programming errors —\n  notably a `steps` key on an override layer.\n- **The cache carries an invalidation generation, and this is where it\n  diverges from `smrt-prompts`.** A resolution captures\n  `getPlaybookCacheGeneration(key, db)` before its asynchronous layer loads and\n  hands it back to `setCachedPlaybookBase()`; a concurrent `save()` / `delete()`\n  bumps the generation, and the in-flight resolution is then refused the cache\n  write instead of repopulating the key it just invalidated with the pre-write\n  value. Without it, \"a stale entry is never served after a write\" held only\n  until a read raced a write, and then failed for the full 30s TTL. Generations\n  are tracked per `(db, key)`, not per tenant, because an app-level row is\n  inherited by every tenant. `clearPlaybookCache()` bumps rather than resets\n  them, so a resolution that started before the clear cannot write back either.\n  `smrt-prompts` and `smrt-languages` still carry the unguarded version of this\n  race; fixing them is separate work.\n- **Restart vitest after adding a decorated class**; the manifest is generated\n  at startup.\n\n## Related\n\n- `@happyvertical/smrt-prompts` — the pattern this package clones\n- `@happyvertical/smrt-languages` — source of the `context` column convention\n- `@happyvertical/smrt-features` — parallel package for feature flags\n- Epic #2585 — declared agent surface; #2587 capability vocabulary,\n  #2588 view intents, #2590 preflight, #2591 manifest emission\n"
+}

package/dist/types.d.ts

@@ -0,0 +1,241 @@
+import { CapabilityClassification } from '@happyvertical/smrt-types';
+import { CapabilityDeclaration } from '@happyvertical/smrt-types';
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+
+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;
+}
+
+export declare interface PlaybookOverrideOptions {
+    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;
+}
+
+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;
+
+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 { }

package/dist/types.js

@@ -0,0 +1,6 @@
+//#region src/types.ts
+var PLAYBOOK_PLANES = Object.freeze(["browser", "server"]);
+//#endregion
+export { PLAYBOOK_PLANES };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type { SmrtClassOptions } from '@happyvertical/smrt-core';\nimport type {\n  CapabilityClassification,\n  CapabilityDeclaration,\n} from '@happyvertical/smrt-types';\n\n/**\n * Execution planes a playbook can declare validity for.\n *\n * `browser` covers WebMCP / in-page agents driving mounted surfaces;\n * `server` covers Node MCP, CLI, and in-app agents running under\n * `executeAsPrincipal`.\n */\nexport type PlaybookPlane = 'browser' | 'server';\n\nexport const PLAYBOOK_PLANES: readonly PlaybookPlane[] = Object.freeze([\n  'browser',\n  'server',\n]);\n\n/**\n * A step naming a model operation by qualified pair — the same qualified\n * form STI discriminators and `@crossPackageRef` already use. Never a\n * generated tool name: that is derived from model, action, and namespace and\n * would silently orphan stored tenant overrides on a namespace change.\n *\n * The step never classifies itself; classification is inherited from the\n * referenced operation (see {@link PlaybookOperationClassifier}).\n */\nexport interface PlaybookOperationStep {\n  kind: 'operation';\n  /** Qualified model name, e.g. `@happyvertical/smrt-commerce:Order`. */\n  model: string;\n  /** Operation name exposed by the model's `@smrt({ api })` surface. */\n  action: string;\n  /** Human-facing label for the agent's narration of this step. */\n  label?: string;\n  /** Longer human-facing description of the step. */\n  description?: string;\n  /** When true, an agent may skip this step without abandoning the plan. */\n  optional?: boolean;\n}\n\n/**\n * A step naming a declared view intent by its identity (#2588). Valid only\n * where a surface is mounted.\n */\nexport interface PlaybookIntentStep {\n  kind: 'intent';\n  /** Declared intent identity from the #2588 intent registry. */\n  id: string;\n  label?: string;\n  description?: string;\n  optional?: boolean;\n}\n\n/** A playbook step. Exactly two kinds exist in v1; playbooks cannot nest. */\nexport type PlaybookStep = PlaybookOperationStep | PlaybookIntentStep;\n\n/**\n * What an agent does when a step fails partway through a plan. Playbooks are\n * scripts, never atomic units, so there is no compensation: the definition\n * says only whether the remainder of the plan is abandoned.\n */\nexport type PlaybookFailurePolicy = 'abort' | 'continue';\n\n/**\n * Fields a stored override layer may change when the definition opts in.\n *\n * `steps` is deliberately absent: it is structurally non-editable, not merely\n * defaulted false. No override layer can carry a step list at all.\n */\nexport interface PlaybookEditableConfig {\n  title: boolean;\n  description: boolean;\n  planes: boolean;\n  onStepFailure: boolean;\n  enabled: boolean;\n  metadata: boolean;\n}\n\nexport type PlaybookMetadata = Record<string, unknown>;\n\nexport interface PlaybookDefinitionInput {\n  key: string;\n  title: string;\n  description: string;\n  steps: readonly PlaybookStep[];\n  /**\n   * Planes this playbook is valid on. Defaults to both planes when every step\n   * is a model operation, and to `['browser']` when any step is a view intent\n   * — server validity for an intent-bearing playbook rides the #2446 browser\n   * command/ack bridge and must be declared explicitly.\n   */\n  planes?: readonly PlaybookPlane[];\n  onStepFailure?: PlaybookFailurePolicy;\n  enabled?: boolean;\n  metadata?: PlaybookMetadata | null;\n  editable?: Partial<PlaybookEditableConfig>;\n}\n\nexport interface PlaybookDefinition {\n  key: string;\n  title: string;\n  description: string;\n  steps: readonly PlaybookStep[];\n  planes: readonly PlaybookPlane[];\n  onStepFailure: PlaybookFailurePolicy;\n  enabled: boolean;\n  metadata: PlaybookMetadata;\n  editable: PlaybookEditableConfig;\n}\n\n/**\n * A partial override from any layer above the code default. There is no\n * `steps` key, and supplying one is rejected rather than ignored.\n */\nexport interface PlaybookConfigOverrideInput {\n  title?: string | null;\n  description?: string | null;\n  planes?: readonly PlaybookPlane[] | null;\n  onStepFailure?: PlaybookFailurePolicy | null;\n  enabled?: boolean | null;\n  metadata?: PlaybookMetadata | null;\n  [key: string]: unknown;\n}\n\nexport interface PlaybookPackageConfig {\n  playbooks?: Record<string, PlaybookConfigOverrideInput>;\n  [key: string]: unknown;\n}\n\n/** One normalized override layer. `null` means \"clear\"; `undefined` means \"inherit\". */\nexport interface PlaybookLayer {\n  title?: string | null;\n  description?: string | null;\n  planes?: readonly PlaybookPlane[] | null;\n  onStepFailure?: PlaybookFailurePolicy | null;\n  enabled?: boolean | null;\n  metadata?: PlaybookMetadata | null;\n}\n\nexport interface PlaybookOverrideOptions {\n  key?: string;\n  tenantId?: string | null;\n  title?: string | null;\n  description?: string | null;\n  planes?: string | readonly PlaybookPlane[] | null;\n  onStepFailure?: PlaybookFailurePolicy | null;\n  enabled?: boolean | null;\n  metadata?: string | PlaybookMetadata | null;\n}\n\n/**\n * Resolves the capability classification of a referenced model operation.\n *\n * Playbooks never classify a step themselves. A host that knows the emitted\n * build-time classification (core's `tool-schema.ts` output, or the runtime\n * manifest) supplies it here; anything it does not know resolves fail-closed\n * to `{ effect: 'destructive', idempotent: false, openWorld: true }`.\n */\nexport type PlaybookOperationClassifier = (\n  step: PlaybookOperationStep,\n) => CapabilityDeclaration | null | undefined;\n\n/**\n * Record returned by an intent registry for a declared view intent.\n *\n * Seam for #2588: until an intent registry exists, no resolver is supplied and\n * an intent step fails resolution closed.\n */\nexport interface PlaybookIntentRecord {\n  id: string;\n  classification?: CapabilityDeclaration | null;\n  planes?: readonly PlaybookPlane[] | null;\n}\n\n/** Seam for #2588. */\nexport type PlaybookIntentResolver = (\n  id: string,\n) => PlaybookIntentRecord | null | undefined;\n\nexport interface ResolvePlaybookOptions {\n  db?: SmrtClassOptions['db'];\n  tenantId?: string | null;\n  /** Plane the calling agent runs on. Defaults to `'server'`. */\n  plane?: PlaybookPlane;\n  /** Highest-precedence layer, supplied per call. */\n  override?: PlaybookConfigOverrideInput;\n  /** Host-supplied classification source for model-operation steps. */\n  classifier?: PlaybookOperationClassifier;\n  /** Host-supplied intent registry (#2588). */\n  intents?: PlaybookIntentResolver;\n}\n\n/** One step of a resolved plan, with its inherited classification. */\nexport interface PlaybookPlanStep {\n  index: number;\n  step: PlaybookStep;\n  classification: CapabilityClassification;\n  /** True when the classification is the fail-closed default. */\n  classificationDeclared: boolean;\n}\n\n/**\n * The output of resolution: a plan an agent follows step by step. Nothing in\n * this package executes a step, and the plan is not an authority boundary —\n * every step is authorized independently where it runs.\n */\nexport interface PlaybookPlan {\n  key: string;\n  title: string;\n  description: string;\n  plane: PlaybookPlane;\n  planes: readonly PlaybookPlane[];\n  onStepFailure: PlaybookFailurePolicy;\n  metadata: PlaybookMetadata;\n  steps: readonly PlaybookPlanStep[];\n}\n\nexport type PlaybookRejectionReason =\n  | 'unknown-playbook'\n  | 'disabled'\n  | 'plane-not-declared'\n  | 'intent-registry-unavailable'\n  | 'unknown-intent'\n  | 'intent-plane-not-declared';\n\nexport interface PlaybookRejection {\n  ok: false;\n  reason: PlaybookRejectionReason;\n  message: string;\n  key: string;\n  /** Index of the offending step, when the rejection is step-scoped. */\n  stepIndex?: number;\n}\n\nexport interface PlaybookAcceptance {\n  ok: true;\n  plan: PlaybookPlan;\n}\n\n/** Resolution fails closed: every rejection carries a specific reason. */\nexport type PlaybookResolution = PlaybookAcceptance | PlaybookRejection;\n\nexport interface PlaybookCacheValue {\n  key: string;\n  title: string;\n  description: string;\n  planes: readonly PlaybookPlane[];\n  onStepFailure: PlaybookFailurePolicy;\n  enabled: boolean;\n  metadata: PlaybookMetadata;\n}\n"],"mappings":";AAeO,IAAM,kBAA4C,OAAO,OAAO,CACrE,WACA,QACF,CAAC"}