@happyvertical/smrt-types 0.43.10 → 0.44.0

package/AGENTS.md

@@ -12,6 +12,7 @@ Shared TypeScript type definitions. Prevents circular dependencies between packa
 | `identity.ts` | `User`, `Tenant`, `Role`, `Membership`, `SmrtEntityFields` — cross-package identity data contracts (runtime classes live in smrt-users, which `implements` these) |
 | `knowledge.ts` | Additive schema-version-1 domain knowledge contracts shared by core generation and development tooling |
 | `data-query.ts` | Serializable bounded query request/result envelope, allowlisted schema, filters, paging, totals, freshness, and facets |
+| `capability.ts` | `CapabilityEffect`, `CapabilityClassification`, `CapabilityDeclaration` — the one classification contract (effect/idempotent/openWorld + fail-closed default) shared by generated model tools, view intents, and playbook steps (#2587) |
 
 ## Rules
 

package/dist/index.d.ts

@@ -137,6 +137,69 @@ export declare interface AiUsageSummaryOptions extends Omit<AiUsageListOptions,
     groupBy?: AiUsageGroupBy;
 }
 
+/**
+ * Fully resolved capability classification for one declared action.
+ *
+ * **Fail-closed rule**: an undeclared capability resolves to
+ * `{ effect: 'destructive', idempotent: false, openWorld: true }` — the most
+ * restrictive exposure a policy can select. Every classifier in the mirror
+ * (core's generator, smrt-web's legacy fallback, and any future declaration
+ * site) MUST apply this exact default rather than inventing its own.
+ *
+ * **CRUD is fixed** and never overridden by a declaration:
+ * - `list` / `get` → `{ effect: 'read', idempotent: true, openWorld: false }`
+ * - `create` → `{ effect: 'write', idempotent: false, openWorld: false }`
+ * - `update` → `{ effect: 'write', idempotent: true, openWorld: false }`
+ * - `delete` → `{ effect: 'destructive', idempotent: true, openWorld: false }`
+ *
+ * Anything else (a custom action, a view intent, a playbook step) resolves
+ * through an explicit {@link CapabilityDeclaration}, defaulted per-field by
+ * the fail-closed rule above.
+ */
+export declare interface CapabilityClassification {
+    effect: CapabilityEffect;
+    /** Whether repeating the action with the same arguments is safe. */
+    idempotent: boolean;
+    /** Whether the action may interact outside the SMRT application. */
+    openWorld: boolean;
+}
+
+/**
+ * An author-supplied, partial classification. Any field a declaration omits
+ * resolves through the fail-closed rule documented on
+ * {@link CapabilityClassification}, never through a CRUD- or name-based guess.
+ */
+export declare type CapabilityDeclaration = Partial<CapabilityClassification>;
+
+/**
+ * One capability classification contract shared by every WebMCP declaration
+ * site (#2587). This module intentionally has no runtime code.
+ *
+ * Core classifies every canonical model tool at build time
+ * (`packages/core/src/generators/tool-schema.ts`) and emits the resolved
+ * `effect` / `idempotent` / `openWorld` on each `webMcpToolDefinitions` entry.
+ * smrt-web's browser registrar trusts that emitted metadata for canonical
+ * definitions instead of recomputing it, and keeps its own CRUD switch only
+ * as the fail-closed fallback for legacy definitions that carry no metadata.
+ * View intents (#2588) classify by this same contract where they are
+ * declared; playbook steps (#2589) inherit classification from the model
+ * operation they reference and never classify anything themselves.
+ *
+ * `smrt-web` cannot import this package — its dependency-DAG guardrails keep
+ * it free of every `@happyvertical/*` dependency (see its AGENTS.md) — so its
+ * `WebMcpToolEffect` mirrors {@link CapabilityEffect} structurally rather than
+ * importing it, the same way `data-query.ts` mirrors this package's bounded
+ * query envelope there. `smrt-core`'s `ToolEffect` (`src/registry/types.ts`)
+ * DOES alias {@link CapabilityEffect} directly, since core already depends on
+ * this package.
+ */
+/**
+ * Browser/agent-visible effect classification for a generated capability.
+ * `'read'` never mutates; `'write'` mutates within the application;
+ * `'destructive'` may remove or irreversibly change data.
+ */
+export declare type CapabilityEffect = 'read' | 'write' | 'destructive';
+
 /** One typed predicate. `in` and `notIn` require a non-empty value array. */
 export declare interface DataQueryCondition {
     kind: 'condition';
@@ -328,6 +391,38 @@ export declare type DataQueryTotal = {
     reason?: string;
 };
 
+/**
+ * The package's declared agent-addressable surface beyond its generated model
+ * tools (#2591).
+ *
+ * Omitted entirely when a package declares no intents, playbooks, or
+ * diagnostics, so an artifact for a package with none stays byte-identical to
+ * what it emitted before this field existed.
+ */
+export declare interface DomainKnowledgeAgentSurface {
+    intents: DomainKnowledgeViewIntent[];
+    playbooks: DomainKnowledgePlaybook[];
+    diagnostics: DomainKnowledgeAgentSurfaceDiagnostic[];
+}
+
+/**
+ * A declaration the scanner recognized but could not emit.
+ *
+ * Recorded rather than dropped: the whole point of emitting the agent surface
+ * is that "what can an agent do here" has one answer, and an invisible
+ * declaration would quietly make that answer wrong. Every message names
+ * `useWebMcpTool`, the escape hatch for a genuinely computed tool set.
+ */
+export declare interface DomainKnowledgeAgentSurfaceDiagnostic {
+    code: string;
+    helper: 'defineIntent' | 'definePlaybook';
+    message: string;
+    /** Declaring module, relative to the package root, in POSIX form. */
+    sourceFile: string;
+    line?: number;
+    column?: number;
+}
+
 /** Per-object configuration controlling domain-knowledge generation and exposure. */
 export declare interface DomainKnowledgeConfig {
     enabled?: boolean;
@@ -428,6 +523,15 @@ export declare interface DomainKnowledgeManifest {
     agentDoc?: string;
     /** Sibling module docs linked from `AGENTS.md`; omitted when the package links none. */
     moduleDocs?: DomainKnowledgeModuleDoc[];
+    /**
+     * Declared view intents and playbooks (#2591). Omitted when the package
+     * declares none, so this field is additive to schema version 1.
+     *
+     * This is deliberately a knowledge-artifact field and not a runtime-manifest
+     * field: `manifest.json` stays runtime-focused, and the agent-addressable
+     * surface is an agent/developer contract.
+     */
+    agentSurface?: DomainKnowledgeAgentSurface;
 }
 
 /** Additive structured signature; `methods: string[]` remains the compatibility surface. */
@@ -479,6 +583,31 @@ export declare interface DomainKnowledgeObject {
     risks: string[];
 }
 
+/** A registered playbook (#2589) as emitted into the knowledge artifact (#2591). */
+export declare interface DomainKnowledgePlaybook {
+    key: string;
+    title: string;
+    description: string;
+    steps: DomainKnowledgePlaybookStep[];
+    planes: Array<'browser' | 'server'>;
+    /** False when `planes` was derived from the step kinds rather than declared. */
+    planesDeclared: boolean;
+    onStepFailure: 'abort' | 'continue';
+    enabled: boolean;
+    /** Declaring module, relative to the package root, in POSIX form. */
+    sourceFile: string;
+}
+
+/** One step of an emitted playbook. Steps never nest another playbook. */
+export declare type DomainKnowledgePlaybookStep = {
+    kind: 'operation';
+    model: string;
+    action: string;
+} | {
+    kind: 'intent';
+    id: string;
+};
+
 /** A single generated surface (one api/cli/mcp/ai operation) exposed by an object. */
 export declare interface DomainKnowledgeSurface {
     kind: DomainKnowledgeSurfaceKind;
@@ -500,6 +629,33 @@ export declare interface DomainKnowledgeTenant {
     field?: string;
 }
 
+/**
+ * A declared view intent (#2588) as emitted into the knowledge artifact (#2591).
+ *
+ * `id` is the entry's identity everywhere: in this artifact, in a playbook step
+ * (`{ kind: 'intent', id }`), and in `smrt doctor`'s surface report. It is
+ * declared, never derived from a namespace, a generated tool name, or a route,
+ * so it survives every rename those could undergo.
+ */
+export declare interface DomainKnowledgeViewIntent {
+    id: string;
+    description: string;
+    /** Resolved through the #2587 fail-closed rule at declaration time. */
+    capability: CapabilityClassification;
+    /** The browser registry this intent compiles into, and what it addresses. */
+    target: Record<string, unknown>;
+    hasInputSchema: boolean;
+    /**
+     * Always exactly `['browser']`. An intent moves mounted browser state; a
+     * server-side agent reaches one only through the #2446 command/ack bridge,
+     * which the referencing playbook declares. Typed as the literal tuple so a
+     * consumer cannot read the contract as wider than it is.
+     */
+    planes: ['browser'];
+    /** Declaring module, relative to the package root, in POSIX form. */
+    sourceFile: string;
+}
+
 /** User↔Tenant↔Role junction. Runtime class: `@happyvertical/smrt-users:Membership`. */
 export declare interface Membership extends SmrtEntityFields {
     userId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-types",
-  "version": "0.43.10",
+  "version": "0.44.0",
   "description": "Shared type definitions for the HAVE SDK",
   "type": "module",
   "main": "./dist/index.js",