@owlmeans/viable-common 0.0.11 → 0.0.13

package/build/slot/schemas.js

@@ -22,4 +22,22 @@ export const SlotCommandPayloadSchema = {
     required: ['type', 'command'],
     additionalProperties: false
 };
+/**
+ * The clone command's arguments, as a signed body carries them.
+ *
+ * `token` is declared because it is SENT — a body field the schema does not declare is stripped
+ * by validation and then verified against a signature the sender made over the whole thing, which
+ * the guard reports as a 401 rather than as the validation gap it is.
+ */
+export const SlotGitCloneArgsSchema = {
+    type: 'object',
+    properties: {
+        remoteUrl: { type: 'string', minLength: 1, maxLength: 2048 },
+        branch: { type: 'string', maxLength: 256, nullable: true },
+        depth: { type: 'number', minimum: 0, nullable: true },
+        token: { type: 'string', maxLength: 4096, nullable: true },
+    },
+    required: ['remoteUrl'],
+    additionalProperties: false,
+};
 //# sourceMappingURL=schemas.js.map

package/build/slot/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/slot/schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGhG,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;SACrC;QACD,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE;gBACxD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE;gBACzD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE;aACxD;SACF;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,IAAI;SAC3B;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;IAC7B,oBAAoB,EAAE,KAAK;CACU,CAAA"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/slot/schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGhG,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;SACrC;QACD,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE;gBACxD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE;gBACzD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE;aACxD;SACF;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,IAAI;SAC3B;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;IAC7B,oBAAoB,EAAE,KAAK;CACU,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;QAC5D,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC1D,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;QACrD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC3D;IACD,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,oBAAoB,EAAE,KAAK;CACmB,CAAA"}

package/build/slot/types.d.ts

@@ -66,6 +66,77 @@ export interface SlotGitCommitResult {
 export interface SlotGitLogResult {
     commits: SlotGitCommitInfo[];
 }
+/**
+ * Bring a remote repository onto the volume.
+ *
+ * `token` is a per-invocation credential and never reaches the tree: the executor passes it
+ * through the process environment for the one fetch, exactly as push and pull already do, so it
+ * appears in no `.git/config`, no remote URL and no argv anything can observe.
+ */
+export interface SlotGitCloneArgs {
+    remoteUrl: string;
+    /** The branch to check out. Absent means whatever the remote calls its default. */
+    branch?: string;
+    /** Fetch depth; 0 means the whole history. Defaults to a shallow fetch. */
+    depth?: number;
+    token?: string;
+}
+export interface SlotGitCloneResult {
+    cloned: boolean;
+    /** The branch actually checked out — the resolved default, when none was asked for. */
+    branch: string;
+    head: SlotGitCommitInfo | null;
+    /** Executor diagnostics, when it has any worth reporting. */
+    result?: string;
+}
+/**
+ * One entry of a {@link SlotFileCommand.StatTree} listing.
+ *
+ * The shape both a publisher and a connector answer with, so a census walks a pod's volume and a
+ * developer's own directory through one contract. `binary` is the executor's own verdict — the
+ * caller has not read the file and cannot form one.
+ */
+export interface FileStat {
+    path: string;
+    bytes: number;
+    binary: boolean;
+    modifiedAt?: string;
+}
+export interface StatTreeArgs {
+    /** Project-relative directory to walk. Absent means the whole project. */
+    dir?: string;
+    /** Entries to return before the answer reports itself truncated. */
+    limit?: number;
+}
+/**
+ * `total` is what the walk SAW, `entries` what it returned.
+ *
+ * The two differ on a truncated walk, and the difference is what tells a caller its picture of the
+ * tree is partial — a bounded listing that reported only what it returned would be indistinguish-
+ * able from a small repository.
+ */
+export interface StatTreeResult {
+    entries: FileStat[];
+    truncated: boolean;
+    total: number;
+}
+export interface ReadHeadArgs {
+    path: string;
+    bytes: number;
+}
+/** Move everything in the project root under `dir`, leaving the named entries where they are. */
+export interface RelocateArgs {
+    dir: string;
+    /** Root-relative names that stay put — the slot's own metadata and markers. */
+    keep?: string[];
+}
+export interface RelocateResult {
+    moved: number;
+    kept: string[];
+}
+export interface RemoveTreeArgs {
+    dir: string;
+}
 /** Arguments a shell command may carry. */
 export interface SlotShellArgs {
     subproject?: SubProject;

package/build/slot/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/slot/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEjH,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,cAAc,CAAA;AAE7E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,WAAW,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,OAAO,CAAA;IACpB,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,iBAAiB,EAAE,CAAA;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/slot/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEjH,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,cAAc,CAAA;AAE7E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,WAAW,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,OAAO,CAAA;IACpB,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,iBAAiB,EAAE,CAAA;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAA;IACf,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,QAAQ,EAAE,CAAA;IACnB,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@owlmeans/viable-common",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "license": "MIT",
-  "description": "Runtime-free contracts of the OwlMeans Viable platform — the analysis, design and metadata shapes of a generated project, its target-shape manifest, the slot command vocabulary and the connector protocol.",
+  "description": "Runtime-free contracts of the OwlMeans Viable platform — the analysis, design and metadata shapes of a generated project, its target-shape manifest, the slot command vocabulary, the connector protocol and the conversion vocabulary.",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
@@ -35,6 +35,13 @@
       "module": "./build/connect/index.js",
       "types": "./build/connect/index.d.ts"
     },
+    "./convert": {
+      "import": "./build/convert/index.js",
+      "require": "./build/convert/index.js",
+      "default": "./build/convert/index.js",
+      "module": "./build/convert/index.js",
+      "types": "./build/convert/index.d.ts"
+    },
     "./integrity": {
       "import": "./build/integrity/index.js",
       "require": "./build/integrity/index.js",
@@ -47,15 +54,16 @@
     "@langchain/core": "^1.2.9",
     "@owlmeans/dep-config": "workspace:*",
     "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/agent-common": "^0.1.18-rc.23",
-    "@owlmeans/entrypoint": "^0.1.18-rc.18",
-    "@owlmeans/error": "^0.1.18-rc.15",
-    "@owlmeans/llm-common": "^0.1.18-rc.19",
-    "@owlmeans/route": "^0.1.18-rc.16"
+    "@owlmeans/agent-common": "^0.1.18-rc.25",
+    "@owlmeans/entrypoint": "^0.1.18-rc.20",
+    "@owlmeans/error": "^0.1.18-rc.17",
+    "@owlmeans/llm-common": "^0.1.18-rc.21",
+    "@owlmeans/route": "^0.1.18-rc.18"
   },
   "publishConfig": {
     "access": "public"

package/src/agent/index.ts

@@ -2,3 +2,4 @@
 export type * from './types.js'
 export * from './spectator/index.js'
 export * from './memory.js'
+export * from './presentation.js'

package/src/agent/presentation.ts

@@ -0,0 +1,335 @@
+/**
+ * A compact, runtime-free description of how an agent message should be presented.
+ *
+ * The server emits this with thinking events and the browser refines it as streaming output
+ * becomes parseable. Keeping the vocabulary here prevents the two runtimes from drifting into
+ * their own guesses about the same model response.
+ */
+export enum AgentMessageCategory {
+  Code = 'code',
+  Diff = 'diff',
+  Structured = 'structured',
+  Markdown = 'markdown',
+  Plain = 'plain',
+}
+
+export enum AgentCodeLanguage {
+  ReactTsx = 'react-tsx',
+  Css = 'css',
+  TypeScript = 'typescript',
+  Json = 'json',
+  Other = 'other',
+}
+
+/** A semantic shape that the manager can render as a purpose-built card. */
+export enum AgentStructuredKind {
+  ToolCalls = 'tool-calls',
+  ArtifactSelection = 'artifact-selection',
+  EntitySelection = 'entity-selection',
+  StoryPlan = 'story-plan',
+  ScreenPlan = 'screen-plan',
+  ComponentPlan = 'component-plan',
+  TransitionPlan = 'transition-plan',
+  EntrypointSelection = 'entrypoint-selection',
+  AccessPolicy = 'access-policy',
+  ScaffoldPlan = 'scaffold-plan',
+  RuntimeDecision = 'runtime-decision',
+  CandidateRanking = 'candidate-ranking',
+  Decision = 'decision',
+  GenericRecord = 'generic-record',
+  GenericList = 'generic-list',
+  GenericValue = 'generic-value',
+}
+
+export enum AgentMarkdownKind {
+  Specification = 'specification',
+  DesignDocument = 'design-document',
+  Documentation = 'documentation',
+}
+
+/** The family of specialist that produced an output, not an authorization role. */
+export enum AgentMessageRole {
+  Technical = 'technical',
+  Analytical = 'analytical',
+  Product = 'product',
+  Ux = 'ux',
+  VisualDesign = 'visual-design',
+  Architect = 'architect',
+  Developer = 'developer',
+  Repair = 'repair',
+  Orchestrator = 'orchestrator',
+}
+
+export interface AgentCodePresentation {
+  category: AgentMessageCategory.Code | AgentMessageCategory.Diff
+  language: AgentCodeLanguage
+  role: AgentMessageRole
+}
+
+export interface AgentStructuredPresentation {
+  category: AgentMessageCategory.Structured
+  structure: AgentStructuredKind
+  role: AgentMessageRole
+}
+
+export interface AgentMarkdownPresentation {
+  category: AgentMessageCategory.Markdown
+  document: AgentMarkdownKind
+  role: AgentMessageRole
+}
+
+export interface AgentPlainPresentation {
+  category: AgentMessageCategory.Plain
+  role: AgentMessageRole
+}
+
+export type AgentMessagePresentation =
+  | AgentCodePresentation
+  | AgentStructuredPresentation
+  | AgentMarkdownPresentation
+  | AgentPlainPresentation
+
+/** The attribution and content available to either side of a thinking event. */
+export interface AgentMessageClassificationInput {
+  agent?: string
+  helper?: string
+  action?: string
+  outputType?: string
+  text?: string
+  value?: unknown
+}
+
+type RecordValue = Record<string, unknown>
+
+const documentActions: Record<string, AgentMarkdownKind> = {
+  'write-specification': AgentMarkdownKind.Specification,
+  'summarize-specification': AgentMarkdownKind.Specification,
+  'write-design-concept': AgentMarkdownKind.DesignDocument,
+  'describe-ui-component': AgentMarkdownKind.DesignDocument,
+  'describe-ui-screen': AgentMarkdownKind.DesignDocument,
+  'describe-ui-layout': AgentMarkdownKind.DesignDocument,
+}
+
+const codeActions = new Set(['code', 'update-code', 'update-code-full'])
+
+/**
+ * The model's schema makes the final output self-describing; while it streams, the helper action
+ * gives the client the same semantic cue before a complete JSON value exists.
+ */
+const structuredActions: Record<string, AgentStructuredKind> = {
+  'choose-files-for-fix': AgentStructuredKind.ArtifactSelection,
+  'list-files-to-fix': AgentStructuredKind.ArtifactSelection,
+  'extract-user-stories-from-spec': AgentStructuredKind.StoryPlan,
+  'derive-connecting-stories': AgentStructuredKind.StoryPlan,
+  'derive-area-scaffold-stories': AgentStructuredKind.StoryPlan,
+  'describe-ux-story-transitions': AgentStructuredKind.TransitionPlan,
+  'find-entrypoint-for-screen': AgentStructuredKind.EntrypointSelection,
+  'describe-api-access': AgentStructuredKind.AccessPolicy,
+  'describe-screen-access': AgentStructuredKind.AccessPolicy,
+  'plan-scaffold': AgentStructuredKind.ScaffoldPlan,
+  'runtime-gate': AgentStructuredKind.RuntimeDecision,
+  'detect-story-with-home-screen': AgentStructuredKind.CandidateRanking,
+}
+
+const asRecord = (value: unknown): RecordValue | undefined =>
+  value != null && typeof value === 'object' && !Array.isArray(value)
+    ? value as RecordValue
+    : undefined
+
+const actionOf = (input: AgentMessageClassificationInput): string => input.action?.toLowerCase() ?? ''
+
+const sourceOf = (input: AgentMessageClassificationInput): string =>
+  `${input.agent ?? ''} ${input.helper ?? ''}`.toLowerCase()
+
+const contentOf = (input: AgentMessageClassificationInput): string => input.text?.trim() ?? ''
+
+/**
+ * Source extraction is an internal context-reduction pass. Its terminal tool call contains only
+ * line ranges, which are useful to the coder but add no useful information to a person's journal.
+ */
+export const isAgentMessageHidden = (input: AgentMessageClassificationInput): boolean =>
+  actionOf(input) === 'source-extract'
+
+/** Maps the attribution that reached the event boundary to the visual specialist family. */
+export const agentMessageRoleOf = (input: AgentMessageClassificationInput): AgentMessageRole => {
+  const source = sourceOf(input)
+  const action = actionOf(input)
+
+  if (action === 'arbitrary-modification' || source.includes('orchestrator')) return AgentMessageRole.Orchestrator
+  if (source.includes('fix')) return AgentMessageRole.Repair
+  if (source.includes('coder') || source.includes('developer') || codeActions.has(action)) return AgentMessageRole.Developer
+  if (source.includes('visual') || source.includes('ui-helper')) return AgentMessageRole.VisualDesign
+  if (source.includes('ux-')) return AgentMessageRole.Ux
+  if (source.includes('business') || source.includes('ba-') || source.includes('analysis') || source.includes('analyst')) return AgentMessageRole.Analytical
+  if (source.includes('product') || source.includes('naming')) return AgentMessageRole.Product
+  if (source.includes('architect') || source.includes('arch') || source.includes('layout-helper') ||
+    source.includes('api-helper') || source.includes('access-helper') || source.includes('datalayer-helper') ||
+    source.includes('domain') || source.includes('nav-helper') || source.includes('ui-com-helper') ||
+    source.includes('ui-state-helper')) return AgentMessageRole.Architect
+  return AgentMessageRole.Technical
+}
+
+/** Pulls a schema argument out of LangChain's serialised tool-call shape. */
+export const agentToolCallArguments = (value: unknown): unknown => {
+  if (!Array.isArray(value) || value.length !== 1) return value
+  const call = asRecord(value[0])
+  return call?.args ?? value
+}
+
+const structuredKindOf = (value: unknown): AgentStructuredKind | undefined => {
+  if (value == null) return undefined
+
+  const toolArgs = agentToolCallArguments(value)
+  const object = asRecord(toolArgs)
+  if (object == null) {
+    if (Array.isArray(toolArgs)) return AgentStructuredKind.GenericList
+    return undefined
+  }
+
+  // Checked ahead of the single-array shapes below: a scaffold plan carries its own `stories`
+  // array (so the StoryPlan check would otherwise swallow it), and a runtime decision straight
+  // from the MODEL never carries `actor`/`worker` — those are added only once the decision is
+  // persisted onto a StoryDesign — so requiring them here missed every live model call.
+  if ('identity' in object && 'guestHome' in object && 'areas' in object && 'stories' in object) {
+    return AgentStructuredKind.ScaffoldPlan
+  }
+  if (Array.isArray(object.jobs) && Array.isArray(object.agents) && 'kv' in object) {
+    return AgentStructuredKind.RuntimeDecision
+  }
+
+  if (Array.isArray(object.files)) return AgentStructuredKind.ArtifactSelection
+  if (Array.isArray(object.entities)) return AgentStructuredKind.EntitySelection
+  if (Array.isArray(object.stories)) return AgentStructuredKind.StoryPlan
+  if (Array.isArray(object.screens)) return AgentStructuredKind.ScreenPlan
+  if (Array.isArray(object.components)) return AgentStructuredKind.ComponentPlan
+  if (Array.isArray(object.transitions)) return AgentStructuredKind.TransitionPlan
+  if (Array.isArray(object.entries)) return AgentStructuredKind.EntrypointSelection
+  if (Array.isArray(object.candidates)) return AgentStructuredKind.CandidateRanking
+  if (Object.values(object).some(value => {
+    const entry = asRecord(value)
+    return entry != null && Array.isArray(entry.permissions) && 'level' in entry
+  })) return AgentStructuredKind.AccessPolicy
+  return AgentStructuredKind.GenericRecord
+}
+
+const decisionAction = (action: string): boolean =>
+  action.startsWith('should-') || action.startsWith('is-') || action.includes('blueprint-case') || action.includes('choose-case')
+
+const fileExtensionLanguage = (path: string): AgentCodeLanguage => {
+  const name = path.toLowerCase().split('?')[0]
+  if (/\.(tsx|jsx)$/.test(name)) return AgentCodeLanguage.ReactTsx
+  if (/\.css$/.test(name)) return AgentCodeLanguage.Css
+  if (/\.(ts|mts|cts|js|mjs|cjs)$/.test(name)) return AgentCodeLanguage.TypeScript
+  if (/\.json$/.test(name)) return AgentCodeLanguage.Json
+  return AgentCodeLanguage.Other
+}
+
+/** Finds the language of a unified diff from its destination (or source) file path. */
+export const agentDiffLanguageOf = (text: string): AgentCodeLanguage => {
+  const match = text.match(/^\+\+\+\s+(?:b\/)?(.+)$/m) ?? text.match(/^---\s+(?:a\/)?(.+)$/m)
+  return match == null ? AgentCodeLanguage.Other : fileExtensionLanguage(match[1])
+}
+
+const fencedLanguageOf = (text: string): AgentCodeLanguage | undefined => {
+  const match = text.match(/^```([\w+-]+)/m)
+  const language = match?.[1]?.toLowerCase()
+  if (language == null) return undefined
+  if (['tsx', 'jsx', 'react'].includes(language)) return AgentCodeLanguage.ReactTsx
+  if (language === 'css') return AgentCodeLanguage.Css
+  if (['ts', 'typescript', 'js', 'javascript'].includes(language)) return AgentCodeLanguage.TypeScript
+  if (language === 'json') return AgentCodeLanguage.Json
+  return AgentCodeLanguage.Other
+}
+
+/** Conservative code detection; prose with one identifier remains plain text. */
+export const agentCodeLanguageOf = (text: string): AgentCodeLanguage => {
+  const content = text.trim().replace(/^```[\w+-]*\n?|\n?```$/g, '')
+  const fenced = fencedLanguageOf(text)
+  if (fenced != null) return fenced
+  if (content === '') return AgentCodeLanguage.Other
+  try {
+    JSON.parse(content)
+    if (/^[{[]/.test(content)) return AgentCodeLanguage.Json
+  } catch {
+    // The remaining heuristics deliberately require source-like syntax.
+  }
+  if (/<[A-Za-z][\w.:-]*(?:\s[^>]*)?\/>|<[A-Za-z][\w.:-]*(?:\s[^>]*)?>/.test(content) &&
+    /\b(import|export|const|function|return)\b/.test(content)) return AgentCodeLanguage.ReactTsx
+  if (/(^|\n)\s*(?:[.#][\w-]+|[a-z][\w-]*(?:\[[^\]]+\])?)\s*\{[^}]*:[^}]*\}/.test(content)) {
+    return AgentCodeLanguage.Css
+  }
+  if (/\b(import|export|interface|type|const|let|function|class)\b/.test(content) &&
+    /[;{}]|=>/.test(content)) return AgentCodeLanguage.TypeScript
+  return AgentCodeLanguage.Other
+}
+
+export const isUnifiedDiff = (text: string): boolean =>
+  /^---\s+.+\n\+\+\+\s+.+/m.test(text) || (/^@@\s+[-+]/m.test(text) && /^(?:\+|-)[^+-]/m.test(text))
+
+const markdownKindOf = (text: string): AgentMarkdownKind | undefined => {
+  if (/^#{1,6}\s+/m.test(text) || /^>\s+/m.test(text) || /^\|.+\|\s*$/m.test(text)) {
+    return AgentMarkdownKind.Documentation
+  }
+  const listItems = text.match(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/gm)?.length ?? 0
+  return listItems >= 2 ? AgentMarkdownKind.Documentation : undefined
+}
+
+/**
+ * Classifies known model output by source AND shape. The `value` comes from a caller's JSON
+ * parser; this runtime-free package intentionally never repairs or parses streamed JSON itself.
+ */
+/**
+ * Actions run by an unconstrained tool-calling loop (the coding agent, the repair/architect/
+ * lookup sub-agents, source extraction) rather than a single pinned-schema call. Their tool calls
+ * are file/shell operations, not model-schema output, so they always render as ToolCalls even
+ * when a call's arguments happen to shape-match a schema kind — `read_sources({ files })` looks
+ * exactly like an ArtifactSelection.
+ */
+const agentLoopActions = new Set([
+  'coding-agent-ask', 'arbitrary-modification', 'fix-agent', 'architect', 'declaration-lookup',
+  'source-extract',
+])
+
+const isGenericStructure = (kind: AgentStructuredKind | undefined): boolean =>
+  kind == null || kind === AgentStructuredKind.GenericRecord || kind === AgentStructuredKind.GenericList ||
+  kind === AgentStructuredKind.GenericValue
+
+export const classifyAgentMessage = (input: AgentMessageClassificationInput): AgentMessagePresentation => {
+  const role = agentMessageRoleOf(input)
+  const action = actionOf(input)
+  const text = contentOf(input)
+  const structure = structuredKindOf(input.value)
+
+  if (input.outputType === 'tool_calls') {
+    // A single pinned-schema call resolves to its own card; everything else — several calls in
+    // one turn, an unconstrained agent-loop action, or a shape too generic to be informative —
+    // is a tool call, not a schema result.
+    const isMultiCall = Array.isArray(input.value) && input.value.length > 1
+    const isToolCalls = isMultiCall || agentLoopActions.has(action) || isGenericStructure(structure)
+    return {
+      category: AgentMessageCategory.Structured,
+      structure: isToolCalls ? AgentStructuredKind.ToolCalls : structure!,
+      role,
+    }
+  }
+  if (structure != null) return { category: AgentMessageCategory.Structured, structure, role }
+  const actionStructure = structuredActions[action]
+  if (actionStructure != null) return { category: AgentMessageCategory.Structured, structure: actionStructure, role }
+  if (decisionAction(action)) return { category: AgentMessageCategory.Structured, structure: AgentStructuredKind.Decision, role }
+  if (isUnifiedDiff(text) || action === 'update-code') {
+    return { category: AgentMessageCategory.Diff, language: agentDiffLanguageOf(text), role }
+  }
+  if (codeActions.has(action) || fencedLanguageOf(text) != null || agentCodeLanguageOf(text) !== AgentCodeLanguage.Other) {
+    return { category: AgentMessageCategory.Code, language: agentCodeLanguageOf(text), role }
+  }
+  const document = documentActions[action] ?? markdownKindOf(text)
+  if (document != null) return { category: AgentMessageCategory.Markdown, document, role }
+  if (input.value != null) {
+    return {
+      category: AgentMessageCategory.Structured,
+      structure: Array.isArray(input.value) ? AgentStructuredKind.GenericList : AgentStructuredKind.GenericValue,
+      role,
+    }
+  }
+  return { category: AgentMessageCategory.Plain, role }
+}

package/src/blueprint/case.ts

@@ -61,8 +61,8 @@ export interface BlueprintCaseDefinition {
 /** What every AI case installs. The langchain peers are declared here, at ONE range. */
 const AI_DEPS = {
   [SubProject.Backend]: {
-    '@owlmeans/llm': '^0.1.18-rc.13',
-    '@owlmeans/agent': '^0.1.18-rc.16',
+    '@owlmeans/llm': '^0.1.18-rc.22',
+    '@owlmeans/agent': '^0.1.18-rc.25',
     '@langchain/core': '^1.2.9',
     '@langchain/anthropic': '^1.5.8',
     '@langchain/openai': '^1.5.10',
@@ -214,7 +214,7 @@ in advance.
         deps: {
           [SubProject.Backend]: {
             ...AI_DEPS[SubProject.Backend],
-            '@owlmeans/agent-skills': '^0.1.18-rc.12',
+            '@owlmeans/agent-skills': '^0.1.18-rc.21',
           },
         },
         libraries: AI_LIBRARIES,