@owlmeans/viable-common 0.0.12 → 0.0.13

package/README.md

@@ -1 +1,68 @@
-# types
+# @owlmeans/viable-common
+
+Runtime-free contracts of the OwlMeans Viable platform.
+
+Viable turns a description into a running full-stack application. Four runtimes have to agree
+about every name involved — the manager API, the agent, the publisher that runs inside a project
+slot, and the connector SDK on a developer's machine — so each of those names is declared here
+once and imported by all of them. There is no runtime in this package: no `@langchain/*`, no
+filesystem, no inference SDK. It is safe to import from a browser bundle.
+
+## What is in it
+
+| Subpath | Contents |
+|---|---|
+| `.` | The shapes a generated project is described by: user stories and entities, the design and scaffold plans, UX/UI specs, the `docs/` metadata paths, the four user areas, the model roles and personas, moderation categories, slot metadata |
+| `@owlmeans/viable-common/slot` | The slot command vocabulary — file, shell and git commands, the sub-project roles, the target's ports and process markers |
+| `@owlmeans/viable-common/connect` | The connector protocol: sessions, operations, model tasks, questions, jobs, capabilities, the error family, and `connectProtocols()` — the one declaration both the platform and the SDK bind |
+| `@owlmeans/viable-common/convert` | Converting an application that already exists: the stages and their transitions, the origin and stack taxonomy, the census classifiers, and the `docs/conversion/` layout |
+| `@owlmeans/viable-common/integrity` | The target-shape manifest — what a slot is allowed to install, build and run — per target layout |
+
+## Installation
+
+```bash
+bun add @owlmeans/viable-common@^0.0.13
+```
+
+## Rules worth knowing before you change something
+
+**A schema is written for the reader that will refuse it.** Model-answer schemas are annotated
+`JSONSchemaType<T>` so a drift from the type is caught where it is written; record schemas are
+hand-written and cast, because they are re-applied as a Mongo `$jsonSchema`, which admits no
+`Record<>` maps, no `integer` and no date objects.
+
+**`nullable: true` always carries its `type`, and a nullable `enum` lists `null` among its
+values.** Ajv checks `nullable` and `enum` independently, so the pair written apart admits `null`
+by type and then refuses it by enum — the field can only ever be omitted, never sent empty. A
+provider's structured output writes an unset optional as `null`, and a wire body where `null`
+means "inherit" has no other spelling. `tests/convert.spec.ts` walks every exported schema for
+both faults, and for draft-04 tuple `items`.
+
+**A field that crosses a version skew carries no `enum`.** A connector is installed with
+`npx -y @owlmeans/viable-mcp@^0.1.18-rc.10` and talks to a separately deployed platform, so an executor kind it
+sends must remain an unused capability on an older platform rather than a refused session.
+
+**A ceiling exists once.** The inquiry answer cap here equals `DEFAULT_INQUIRY_ANSWER_CHARS` in
+`@owlmeans/llm-common` and must stay equal; two ceilings mean the larger one truncates silently
+at the smaller.
+
+## Related
+
+- `@owlmeans/viable-sdk` — the connector SDK written against these contracts
+- `@owlmeans/viable-mcp` — the npx MCP server built on that SDK
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.21
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/viable-common",
+  "version": "0.0.13",
+  "generatedAt": "2026-09-15T12:21:31.931Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "agent-presentation",
+      "category": "package-specific",
+      "file": "skills/agent-presentation/SKILL.md",
+      "canonicalPath": ".agents/skills/agent-presentation/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "viable-common",
+      "category": "package-specific",
+      "file": "skills/viable-common/SKILL.md",
+      "canonicalPath": ".agents/skills/viable-common/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/agent-presentation/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agent-presentation
+description: Shared, runtime-free taxonomy for presenting OwlMeans Viable agent output. Use when classifying LLM thinking/history messages, adding semantic structured-output cards, or changing their server-to-browser event contract.
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Agent output presentation
+
+`@owlmeans/viable-common`'s `agent/presentation.ts` owns the browser-safe vocabulary for agent
+output. Keep the server and every client on `classifyAgentMessage()`; consumers may refine a
+provisional classification as streamed text becomes parseable, but must not invent a competing
+taxonomy.
+
+## Contract
+
+- The top-level categories are code, unified diff, structured output, Markdown and plain text.
+  Code and diffs carry one of React TSX, CSS, TypeScript, JSON or other; structured output carries
+  a semantic kind; Markdown carries a document kind; every presentation carries a specialist role.
+- Classify from the combined source: agent, helper, action, explicit output type, text and parsed
+  value. Helper/agent attribution selects the specialist family; content shape alone is not enough.
+- A transport may send `presentation` on thinking start and stop events. It is optional for rolling
+  compatibility; the final server hint is based on complete output and the browser refines it while
+  it streams. Keep legacy `outputType` intact.
+- Unwrap a single LangChain tool call's `args` before semantic classification
+  (`agentToolCallArguments`). Known schemas render as cards; unknown objects and arrays remain
+  generic structured output, never raw JSON.
+- `structuredKindOf`'s shape checks are ORDER-SENSITIVE where one payload could match more than
+  one: a scaffold plan carries its own `stories` array, so `ScaffoldPlan` (`identity` + `guestHome`
+  + `areas` + `stories`) is checked before the bare `StoryPlan` (`stories` alone) check catches it
+  first. `RuntimeDecision` matches on `jobs` + `agents` + `kv` alone — NOT `actor`/`worker`, which
+  the live model call never sends (those two are added only once a decision is persisted onto a
+  `StoryDesign`); requiring them missed every runtime-decision call the model actually makes.
+- `outputType === 'tool_calls'` does not automatically mean `AgentStructuredKind.ToolCalls`: a
+  SINGLE pinned-schema call (`choose-files-for-fix`, `plan-scaffold`, …) still renders as its own
+  schema card. It reads as `ToolCalls` when any of these holds: more than one call arrived in the
+  same turn, the action belongs to an unconstrained tool-calling loop (`agentLoopActions` —
+  `coding-agent-ask`, `arbitrary-modification`, `fix-agent`, `architect`, `declaration-lookup`,
+  `source-extract`), or the single call's shape only reaches a `Generic*` kind. Without the
+  action check, a free-flight `read_sources({ files })` call reads as an `ArtifactSelection` card
+  instead of a tool call, because its args happen to shape-match that schema.
+- `isAgentMessageHidden()` owns utility-run suppression. The source extractor's `source-extract`
+  range-selection calls are internal context reduction and never render in thinking or history.
+
+## Consumer rules
+
+- Treat Markdown as a compact draft, not as a full document. Keep raw HTML disabled.
+- Use one token renderer for code and diff code portions; infer a diff language from its changed path.
+- Plain text remains plain. Empty live output is an activity state, not a fabricated model response.
+- Labels for known structured fields belong to the consuming app's i18n resources. Open model keys
+  should be humanized rather than passed through an unbounded translation namespace.
+- This package classifies WHICH kind and category a message is; it says nothing about how a
+  consumer renders one. `product-viable`'s manager-web renders every `AgentStructuredKind` as a
+  flat typed result card and captures per-tool-call outcomes as a platform-side thinking event
+  (`AgentThinkingType.ToolResult`, in `sources/common`, not this package) — see that repo's
+  `agent-output-cards` skill before changing either side of this contract.
+
+## External docs
+
+- https://github.com/remarkjs/react-markdown/blob/main/readme.md — safe-by-default Markdown with custom React components.
+- https://github.com/remarkjs/remark-gfm — GFM tables, task lists, autolinks and strikethrough plugin.
+- https://github.com/FormidableLabs/prism-react-renderer — React token rendering for compact source views.
+- https://fontsource.org/fonts/jetbrains-mono/install — self-hosted variable JetBrains Mono for Vite apps.

package/agent-meta/skills/viable-common/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: viable-common
+description: How to use @owlmeans/viable-common — the runtime-free contract package of the OwlMeans Viable platform. Covers the slot command vocabulary and target layouts, the target-shape integrity manifest, the connector protocol and its entrypoints, the conversion vocabulary, the analysis/design/metadata shapes a generated project is described by, the schema conventions every model answer and stored record here is written to (nullable with its type, a nullable enum carrying null, no Record maps in a record schema), and the version-skew rule a name on the wire obeys. Auto-invoked when importing a slot command, a connector or conversion type, a target-integrity helper, or any *Schema this package exports.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/viable-common
+
+**Layer:** Cross-cutting domain (contracts only)
+**Install:** `"@owlmeans/viable-common": "^0.0.13"` in `dependencies`
+**Subpaths:** `.` · `./slot` · `./connect` · `./convert` · `./integrity`
+**Runtime-free:** no `@langchain/*`, no filesystem, no Ajv at run time (a devDependency, for the
+tests that compile the schemas). It depends on `@owlmeans/entrypoint`, `@owlmeans/route`,
+`@owlmeans/error`, `@owlmeans/agent-common` and `@owlmeans/llm-common` and on nothing else.
+
+Every name the OwlMeans Viable platform puts on a wire, on a volume or in a prompt is declared
+here once, and the four runtimes that must agree about it — the manager API, the agent, the
+publisher/production runtime, and the connector SDK on somebody's laptop — all read the same
+declaration. A vocabulary copied instead of imported is how one tree gets two totals, one
+refusal two spellings, and one ceiling two values.
+
+## Key Exports
+
+| Subpath | What it declares |
+|---|---|
+| `.` (barrel) | `SlotMetadata` and the three metadata vocabularies (`metadataConfigs`, `metadataLists`, `metadataSecrets`); `ProjectArea` / `AREA_PATHS` / `AREA_ACCESS` / `AREA_TIER`; `ModelRole` and the viable `ExecutionState`; `ViableSkill` / `ViablePersona` / `VIABLE_SKILLS`; the BA, dev, UX, design and scaffold shapes and their schemas; `ModerationCategory` / `ModerationSubject` / `decideModeration`; the `docs/` metadata paths; `PreviewEventType` |
+| `./slot` | `SlotCommandType` and the `SlotFileCommand` / `SlotShellCommand` / `SlotGitCommand` sets, `SubProject`, `WorkloadKind`, the target ports and process markers, `slotOrigin` / `targetRedirectUrisForOrigin` |
+| `./connect` | `ConnectTarget`, `ConnectLlm`, `ConnectHarness`, `ConnectExecutor`, `ConnectOpKind`, `ConnectJobKind`/`Status`/`Block`, `ModelTier` + `tierOfRole`/`clampTier`, `ModelTask*`, `InquiryPayload` + `ConnectInquiryKind`, the session/job/status views, the `Connect*` error family, `connectProtocols(opts)` and every `*Schema` behind them |
+| `./convert` | `ConversionStage`/`Status`/`Decision` and the `stageAfter`/`decisionFor`/`canEnter` transitions, `OriginKind`/`Shape`/`State`, `StackId` + `STACK_FAMILY`, `ArchitectureCase`, `ConvertibilityVerdict`/`Reason`, the census classifiers (`fileClassOf`, `sizeClassOf`, `entropyClassOf`, `binaryByExtension`), the `docs/conversion/` paths, `CONVERTED_ORIGIN_DIR`, `SOURCE_LIST_EXCLUSIONS`, `CENSUS_SKIP_DIRS`, `RELOCATE_ALWAYS_KEEP`, and the model-answer schemas the conversion asks with |
+| `./integrity` | `TargetLayout` + `TARGET_LAYOUTS`, `detectTargetLayout`, `verifyTargetShape`, `TARGET_INTEGRITY_FILES`, `TARGET_PROTECTED_FILES`, `isLegacyLayout`, `targetPackageName` |
+
+## A schema here is written for the reader that will refuse it
+
+Two populations live side by side and are written differently on purpose. Getting the population
+wrong is not a style error — each reader refuses a different thing, and one of them refuses at
+boot rather than at the call.
+
+**Model-answer schemas** are the shape a model's single JSON object must take. Annotate them
+`JSONSchemaType<T>` — checked, not cast — because the answer is parsed straight back into that
+type, and a schema that drifted fails at run time with a message about a document rather than
+about a field.
+
+**Record-element schemas** describe what the platform stores and puts on the wire. They are
+hand-written and cast, because they are re-applied as a Mongo `$jsonSchema`, which is stricter
+than Ajv: no `Record<>` maps (an open key space cannot be validated), no `integer` (a stored
+number is a double), dates as ISO strings rather than objects.
+
+Three rules hold for both, and `tests/convert.spec.ts` walks **the package barrel** for each —
+not the conversion barrel, although the file is the conversion's, because none of the three
+faults is particular to a conversion and a walk over one directory lets the same shape through
+in a design, a slot or a connector schema:
+
+- **`nullable: true` always carries its `type`.** Ajv refuses `nullable` on its own, and a schema
+  that fails to compile takes down whatever compiled it — the route registration, the collection
+  validator — instead of the one call that would have carried the value.
+- **A nullable ENUM lists `null` among its values**: `enum: [...Object.values(X), null]`.
+  `nullable` and `enum` are separate keywords checked independently, so the pair written apart
+  widens the type check to admit `null` and then refuses that very value by enum — the field can
+  only ever be OMITTED, never sent empty. Nothing fails at compile time and nothing fails for a
+  caller that leaves the key out, which is why it survives review; it surfaces as the one caller
+  that spells absence as `null`. Both callers exist here: a provider's structured output writes an
+  unset optional as `null` (an intake stack call was retried three times and discarded as
+  `llm:retry-exceeded`), and a wire body where `null` MEANS something — `llmMode`, "inherit the
+  profile's setting" — has no other spelling at all.
+- **`items` is never an array.** A draft-04 tuple is refused wherever the schema reaches a
+  provider or a collection validator.
+
+**A field that crosses a version skew carries no `enum`.** Users run
+`npx -y @owlmeans/viable-mcp@^0.1.18-rc.10` (the moving prerelease tag) against a separately deployed
+platform, so `ConnectCapabilitiesSchema.executors.items`
+is a bare string: a newer executor kind must stay an unused capability on an older platform, never
+a refused session. Apply the same reasoning to anything else a newer connector may send an older
+platform, and nowhere else — a closed set is worth more than a tolerant one everywhere both ends
+deploy together.
+
+## One immutable protocol tree, bound in each runtime
+
+`connectProtocols(opts)` is the connector's whole immutable HTTP and socket tree — aliases, paths,
+methods, contracts and protocol parents. The manager and SDK bind their own local materializations
+from those declarations, so a path or schema cannot differ across a server and client. Only what
+belongs to the DEPLOYMENT is injected: the guard alias, ownership gate, paid local-LLM gate and the
+platform's update-base protocol.
+
+Adding a route means adding it here first, then binding that named protocol in every runtime that
+serves or calls it. A route declared on one side alone is a 404 nobody can explain from the failing
+end. Keep raw aliases private to declaration modules; consumers receive protocol objects, and a
+dynamic adapter reads `.alias` only at its string-addressed boundary.
+
+## Closed sets that mean something
+
+- **`ProjectArea`** — guest `/`, user `/frontoffice`, admin `/admin`, operator `/backoffice`. A
+  generated product's own roles map onto `user` or `operator`; there is no fifth area. `AREA_PATHS`,
+  `AREA_ACCESS` and `AREA_TIER` are total over it.
+- **`TargetLayout` + `TARGET_LAYOUTS`** — the integrity manifest is PER LAYOUT. A volume never
+  migrates, so a project created before the restructure stays on the legacy tree forever and must
+  verify **clean**; `TARGET_INTEGRITY_FILES` is the union over layouts so a caller has both probes
+  before it knows which tree it holds, and an absent layout reads as the CURRENT one.
+- **`SubProject`** — a ROLE vocabulary mapped per layout, never joined onto a path. Both
+  generations arrive on the wire at once, so the enum must stay total over what any live agent may
+  send, and no role but `Common` may resolve to the `common` directory.
+- **`ConversionStage`** — advanced only through `stageAfter` / `canEnter` / `decisionFor`. A stage
+  transition computed at a call site is how a conversion re-enters a stage it already paid for.
+- **`ModerationCategory`** — a wire contract with seven languages of wording behind it. A fifth
+  shape is PHRASED into one of the four, never added.
+
+## The conversion vocabulary is shared with three executors that walk the same tree
+
+The census, listing and relocation commands are one contract with three implementations — the
+SDK's local executor, the publisher's file helper, and the library's in-process helper — so
+anything they could disagree about is a constant HERE rather than a matching local copy:
+`CENSUS_SKIP_DIRS` (`node_modules`, `.git` — and deliberately not `dist`/`build`/`.next`, ordinary
+directory names an origin may keep sources in), `SOURCE_LIST_EXCLUSIONS` (the metadata directories
+plus `CONVERTED_ORIGIN_DIR`), `BINARY_PROBE_BYTES`, `CENSUS_MAX_HEAD_BYTES`, `RELOCATE_ALWAYS_KEEP`.
+The one thing they are allowed to differ about is stated rather than inherited: the platform's two
+keep what a volume it owns must not lose, the SDK's keeps what a DEVELOPER owns (`.viable`, the two
+`.env` files).
+
+`docs/conversion/` is likewise addressed only through the exported path builders
+(`CONVERSION_*_FILE`, `conversionStoryDoc`, `conversionSeedDoc`) — a conversion's own artifacts are
+read back by the purge, and a path spelled at a call site is a file the purge leaves behind.
+
+## The inquiry vocabulary is a deliberate COPY, and the ceiling is not
+
+`ConnectInquiryKind` / `InquiryPayload` / `InquiryAnswerPayload` mirror `@owlmeans/llm-common`'s
+`Inquiry` family, renamed so both vocabularies can be imported into one file and so `manager-api`,
+which does not depend on the model runtime, stays free of it. Values are byte-identical, so the
+platform's mapper is a widening rather than a translation table, and a test pins that — the same
+arrangement `ModelTask` has with `DelegatedTask`.
+
+The CEILING is not copied twice over: `CONNECT_INQUIRY_MAX_TEXT` equals
+`DEFAULT_INQUIRY_ANSWER_CHARS` and must stay equal, and `./convert`'s own
+`INQUIRY_STATE_TEXT_CHARS` — what a pipeline STATE may keep of an answer's prose, the rest going to
+`docs/conversion/inquiries.md` — equals its twin of the same name there. Two ceilings for one value means the layer with the larger one
+truncates silently at the smaller, and the caller records an assumption about an answer the person
+actually gave. Never introduce a local cap; import the one that exists.
+
+## Errors: declared here, phrased where they are read
+
+`ConnectError` and its family (`ConnectSessionNotFound`, `ConnectSessionGone`, `ConnectOpTimeout`,
+`ConnectOpRefused`, `LocalSlotUnsupported`, `ConnectOpUnknown`) are `ResilientError` classes with
+markers under `viable-connect:`. `ConnectSessionGone` is registered FATAL on the agent side: a run
+whose executor has gone away must stop at once rather than spend a retry ladder, and the step fails
+as an OUTCOME so the run row records where it stopped and `pipeline.resume` picks it up when a
+connector returns.
+
+The platform's own refusals — conversion, moderation, reserved names, integrity — are declared in
+the product repo, not here, so a consumer that cannot `instanceof` them matches by MARKER instead:
+`@owlmeans/viable-sdk`'s `REFUSALS` map and the manager's `useErrorPhrase` read the same substrings,
+which is what stops one refusal being phrased two ways. When a marker changes, both readers change
+with it.
+
+## Tests
+
+`bun test ./tests` — offline. `convert.spec.ts` (the three structural walks over the barrel, the
+conversion schemas compiling, a nullable enum accepting `null` under Ajv while still refusing an
+unknown member, the census classifiers and the stage transitions), `connect-convert.spec.ts` (the
+conversion routes at their paths and methods, hanging under the connector base and carrying no paid
+gate; capabilities accepting an executor kind this platform has never heard of; the answer and
+resume bodies), `design.spec.ts` (the design aggregate, staleness ranking, and the design schema
+refusing an undeclared field or an area outside the closed set).
+
+## Depends On
+
+- `@owlmeans/entrypoint`, `@owlmeans/route` — the entrypoint declarations
+- `@owlmeans/error` — the `Connect*` error family
+- `@owlmeans/llm-common` — `ExecutionEffort`/`ExecutionLevel`, `PromptPolicy`, `LlmPurpose`, and the
+  inquiry ceilings this package's copies are pinned to
+- `@owlmeans/agent-common` — the run and pipeline contracts a conversion's runs are declared against
+
+## Related
+
+- [[viable-sdk]] — the connector SDK written entirely against these contracts
+- [[viable-mcp]] — the npx stdio server built on that SDK
+- [[inquiry]] — the primitive `InquiryPayload` mirrors, and the one answer ceiling
+- [[llm-common]] — the contracts half of the model runtime
+- The DOMAIN rules for what these shapes mean — target areas and navigation, the scaffold, target
+  integrity, the metadata files, the converter — live in the downstream repos that implement them
+  (`target-areas`, `scaffolding`, `workload-integrity`, `viable-metadata`, `converter`). This skill
+  owns the CONTRACT: how a name is declared, and what refuses it.

package/build/agent/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './types.js';
 export * from './spectator/index.js';
 export * from './memory.js';
+export * from './presentation.js';
 //# sourceMappingURL=index.d.ts.map

package/build/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA"}

package/build/agent/index.js

@@ -1,3 +1,4 @@
 export * from './spectator/index.js';
 export * from './memory.js';
+export * from './presentation.js';
 //# sourceMappingURL=index.js.map

package/build/agent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA"}

package/build/agent/presentation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 declare enum AgentMessageCategory {
+    Code = "code",
+    Diff = "diff",
+    Structured = "structured",
+    Markdown = "markdown",
+    Plain = "plain"
+}
+export declare 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 declare 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 declare enum AgentMarkdownKind {
+    Specification = "specification",
+    DesignDocument = "design-document",
+    Documentation = "documentation"
+}
+/** The family of specialist that produced an output, not an authorization role. */
+export declare 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;
+}
+/**
+ * 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 declare const isAgentMessageHidden: (input: AgentMessageClassificationInput) => boolean;
+/** Maps the attribution that reached the event boundary to the visual specialist family. */
+export declare const agentMessageRoleOf: (input: AgentMessageClassificationInput) => AgentMessageRole;
+/** Pulls a schema argument out of LangChain's serialised tool-call shape. */
+export declare const agentToolCallArguments: (value: unknown) => unknown;
+/** Finds the language of a unified diff from its destination (or source) file path. */
+export declare const agentDiffLanguageOf: (text: string) => AgentCodeLanguage;
+/** Conservative code detection; prose with one identifier remains plain text. */
+export declare const agentCodeLanguageOf: (text: string) => AgentCodeLanguage;
+export declare const isUnifiedDiff: (text: string) => boolean;
+export declare const classifyAgentMessage: (input: AgentMessageClassificationInput) => AgentMessagePresentation;
+//# sourceMappingURL=presentation.d.ts.map

package/build/agent/presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../src/agent/presentation.ts"],"names":[],"mappings":"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"}