@owlmeans/viable-common 0.0.44 → 0.0.45

package/build/topology/helpers.js

@@ -1,112 +1,16 @@
-import { LAYOUT_TOPOLOGIES, DEFAULT_TOPOLOGY } from './consts.js';
-/**
- * Order the packages so that nothing is built before what it compiles against.
- *
- * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
- * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
- * not brought in yet, and refusing to order the tree would take the whole build down over one
- * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
- * cannot be built correctly in any order, so the useful behaviour is to build it in the order
- * somebody wrote rather than to throw.
- */
-export const orderPackages = (packages) => {
-    const known = new Set(packages.map(pkg => pkg.name));
-    const index = new Map(packages.map((pkg, at) => [pkg.name, at]));
-    const pending = new Map(packages.map(pkg => [
-        pkg.name, pkg.dependsOn.filter(dep => known.has(dep) && dep !== pkg.name).length,
-    ]));
-    const dependents = new Map();
-    for (const pkg of packages) {
-        for (const dep of pkg.dependsOn) {
-            if (!known.has(dep) || dep === pkg.name)
-                continue;
-            dependents.set(dep, [...dependents.get(dep) ?? [], pkg.name]);
-        }
-    }
-    const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
-    const out = [];
-    // Ready packages are taken in DECLARATION order, not in the order they became ready. Both are
-    // correct builds; only one is the same list every time and the same list a person wrote, and
-    // this order is compared against the shipped layout tables by a test.
-    const ready = packages.filter(pkg => pending.get(pkg.name) === 0).map(pkg => pkg.name);
-    const take = () => {
-        if (ready.length === 0)
-            return undefined;
-        let at = 0;
-        for (let i = 1; i < ready.length; i++) {
-            if ((index.get(ready[i]) ?? 0) < (index.get(ready[at]) ?? 0))
-                at = i;
-        }
-        return ready.splice(at, 1)[0];
-    };
-    for (let name = take(); name != null; name = take()) {
-        const pkg = byName.get(name);
-        if (pkg == null)
-            continue;
-        out.push(pkg);
-        for (const next of dependents.get(name) ?? []) {
-            const left = (pending.get(next) ?? 0) - 1;
-            pending.set(next, left);
-            if (left === 0)
-                ready.push(next);
-        }
-    }
-    const seen = new Set(out.map(pkg => pkg.name));
-    return [...out, ...packages.filter(pkg => !seen.has(pkg.name))];
-};
-/** Resolve the derived halves — build order, library order and the role index. */
-export const resolveTopology = (topology) => {
-    const ordered = orderPackages(topology.packages);
-    const byRole = {};
-    for (const pkg of ordered) {
-        for (const role of pkg.roles) {
-            byRole[role] = [...byRole[role] ?? [], pkg];
-        }
-    }
-    return {
-        ...topology,
-        packages: ordered,
-        build: ordered.map(pkg => pkg.name),
-        libraries: ordered.filter(pkg => pkg.kind === 'library').map(pkg => pkg.name),
-        byRole,
-    };
-};
-/** The default topology for a layout already decided. */
-export const topologyOf = (layout) => LAYOUT_TOPOLOGIES[layout] ?? DEFAULT_TOPOLOGY;
-/**
- * The directory a role names, or `null` when this topology has no package for it.
- *
- * `null` rather than the role's own name: a command aimed at a package the tree does not have must
- * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
- * which is how a type check once ran against the shared package instead of the one under repair.
- */
-export const packageForRole = (topology, role) => topology.byRole[role]?.[0] ?? null;
-/** Every package holding a role — more than one only where a topology splits that role. */
-export const packagesForRole = (topology, role) => topology.byRole[role] ?? [];
-/** The package serving an area, for a topology that splits the browser app across several. */
-export const packageForArea = (topology, role, area) => {
-    const candidates = packagesForRole(topology, role);
-    return candidates.find(pkg => pkg.areas?.includes(area) === true)
-        ?? candidates.find(pkg => pkg.areas == null)
-        ?? candidates[0]
-        ?? null;
-};
-/** `<dir>/<package>` — the only place a topology directory is composed. */
-export const packageDir = (topology, pkg) => `${topology.dir}/${pkg.name}`;
-/**
- * Merge a package into a topology, by name.
- *
- * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
- * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
- * does not. Replacing by name rather than appending keeps a re-classification idempotent.
- */
-export const withPackage = (topology, pkg) => ({
-    ...topology,
-    packages: topology.packages.some(known => known.name === pkg.name)
-        ? topology.packages.map(known => known.name === pkg.name ? pkg : known)
-        : [...topology.packages, pkg],
-});
-/** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
-export const sameTopology = (a, b) => JSON.stringify(orderPackages(a.packages)) === JSON.stringify(orderPackages(b.packages))
-    && a.dir === b.dir;
+import { topologyHelper } from './resolve.js';
+/** @deprecated compat:factory-refactor — use `topologyHelper.orderPackages(…)` */
+export const orderPackages = (packages) => topologyHelper.orderPackages(packages);
+/** @deprecated compat:factory-refactor — use `topologyHelper.resolveTopology(…)` */
+export const resolveTopology = (topology) => topologyHelper.resolveTopology(topology);
+/** @deprecated compat:factory-refactor — use `topologyHelper.packageForRole(…)` */
+export const packageForRole = (topology, role) => topologyHelper.packageForRole(topology, role);
+/** @deprecated compat:factory-refactor — use `topologyHelper.packageForArea(…)` */
+export const packageForArea = (topology, role, area) => topologyHelper.packageForArea(topology, role, area);
+/** @deprecated compat:factory-refactor — use `topologyHelper.packageDir(…)` */
+export const packageDir = (topology, pkg) => topologyHelper.packageDir(topology, pkg);
+/** @deprecated compat:factory-refactor — use `topologyHelper.withPackage(…)` */
+export const withPackage = (topology, pkg) => topologyHelper.withPackage(topology, pkg);
+/** @deprecated compat:factory-refactor — use `topologyHelper.sameTopology(…)` */
+export const sameTopology = (a, b) => topologyHelper.sameTopology(a, b);
 //# sourceMappingURL=helpers.js.map

package/build/topology/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/topology/helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/topology/helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAG7C,kFAAkF;AAClF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAmC,EAA6B,EAAE,CAC9F,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;AAExC,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAA4B,EAAoB,EAAE,CAChF,cAAc,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAA;AAE1C,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAA0B,EAAE,IAAgB,EAAkC,EAAE,CAC7G,cAAc,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;AAE/C,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,QAA0B,EAAE,IAAgB,EAAE,IAAiB,EAC/B,EAAE,CAAC,cAAc,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAExF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAA4B,EAAE,GAA4B,EAAU,EAAE,CAC/F,cAAc,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;AAE1C,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAA4B,EAAE,GAA4B,EAAsB,EAAE,CAC5G,cAAc,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;AAE3C,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAqB,EAAE,CAAqB,EAAW,EAAE,CACpF,cAAc,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA"}

package/build/topology/index.d.ts

@@ -1,5 +1,8 @@
 export type * from './types.js';
+export type * from './resolve/types.js';
+export type * from './card/types.js';
 export * from './consts.js';
+export * from './resolve.js';
 export * from './helpers.js';
 export * from './card.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,oBAAoB,CAAA;AACvC,mBAAmB,iBAAiB,CAAA;AAEpC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA"}

package/build/topology/index.js

@@ -1,4 +1,5 @@
 export * from './consts.js';
+export * from './resolve.js';
 export * from './helpers.js';
 export * from './card.js';
 //# sourceMappingURL=index.js.map

package/build/topology/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA"}

package/build/topology/resolve/types.d.ts

@@ -0,0 +1,47 @@
+import type { ProjectArea } from '../../areas/consts.js';
+import type { TargetLayout } from '../../integrity/consts.js';
+import type { SubProject } from '../../slot/consts.js';
+import type { ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor } from '../types.js';
+/** A target's package arrangement: build order, the role index, and where each package lives. */
+export interface TopologyHelper {
+    /**
+     * Order the packages so that nothing is built before what it compiles against.
+     *
+     * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
+     * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
+     * not brought in yet, and refusing to order the tree would take the whole build down over one
+     * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
+     * cannot be built correctly in any order, so the useful behaviour is to build it in the order
+     * somebody wrote rather than to throw.
+     */
+    orderPackages: (packages: TargetPackageDescriptor[]) => TargetPackageDescriptor[];
+    /** Resolve the derived halves — build order, library order and the role index. */
+    resolveTopology: (topology: TopologyDescriptor) => ResolvedTopology;
+    /** The default topology for a layout already decided. */
+    topologyOf: (layout: TargetLayout) => TopologyDescriptor;
+    /**
+     * The directory a role names, or `null` when this topology has no package for it.
+     *
+     * `null` rather than the role's own name: a command aimed at a package the tree does not have must
+     * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
+     * which is how a type check once ran against the shared package instead of the one under repair.
+     */
+    packageForRole: (topology: ResolvedTopology, role: SubProject) => TargetPackageDescriptor | null;
+    /** Every package holding a role — more than one only where a topology splits that role. */
+    packagesForRole: (topology: ResolvedTopology, role: SubProject) => TargetPackageDescriptor[];
+    /** The package serving an area, for a topology that splits the browser app across several. */
+    packageForArea: (topology: ResolvedTopology, role: SubProject, area: ProjectArea) => TargetPackageDescriptor | null;
+    /** `<dir>/<package>` — the only place a topology directory is composed. */
+    packageDir: (topology: TopologyDescriptor, pkg: TargetPackageDescriptor) => string;
+    /**
+     * Merge a package into a topology, by name.
+     *
+     * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
+     * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
+     * does not. Replacing by name rather than appending keeps a re-classification idempotent.
+     */
+    withPackage: (topology: TopologyDescriptor, pkg: TargetPackageDescriptor) => TopologyDescriptor;
+    /** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
+    sameTopology: (a: TopologyDescriptor, b: TopologyDescriptor) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/topology/resolve/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/topology/resolve/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhG,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,QAAQ,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,CAAA;IACjF,kFAAkF;IAClF,eAAe,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,gBAAgB,CAAA;IACnE,yDAAyD;IACzD,UAAU,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,kBAAkB,CAAA;IACxD;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,KAAK,uBAAuB,GAAG,IAAI,CAAA;IAChG,2FAA2F;IAC3F,eAAe,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,KAAK,uBAAuB,EAAE,CAAA;IAC5F,8FAA8F;IAC9F,cAAc,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,KAAK,uBAAuB,GAAG,IAAI,CAAA;IACnH,2EAA2E;IAC3E,UAAU,EAAE,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,EAAE,uBAAuB,KAAK,MAAM,CAAA;IAClF;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,EAAE,uBAAuB,KAAK,kBAAkB,CAAA;IAC/F,8FAA8F;IAC9F,YAAY,EAAE,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAA;CACxE"}

package/build/topology/resolve/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/topology/resolve/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/topology/resolve/types.ts"],"names":[],"mappings":""}

package/build/topology/resolve.d.ts

@@ -0,0 +1,4 @@
+import type { TopologyHelper } from './resolve/types.js';
+export declare const createTopologyHelper: () => TopologyHelper;
+export declare const topologyHelper: TopologyHelper;
+//# sourceMappingURL=resolve.d.ts.map

package/build/topology/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/topology/resolve.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,eAAO,MAAM,oBAAoB,QAAO,cA0GvC,CAAA;AAED,eAAO,MAAM,cAAc,gBAAyB,CAAA"}

package/build/topology/resolve.js

@@ -0,0 +1,89 @@
+import { LAYOUT_TOPOLOGIES, DEFAULT_TOPOLOGY } from './consts.js';
+export const createTopologyHelper = () => {
+    const orderPackages = (packages) => {
+        const known = new Set(packages.map(pkg => pkg.name));
+        const index = new Map(packages.map((pkg, at) => [pkg.name, at]));
+        const pending = new Map(packages.map(pkg => [
+            pkg.name, pkg.dependsOn.filter(dep => known.has(dep) && dep !== pkg.name).length,
+        ]));
+        const dependents = new Map();
+        for (const pkg of packages) {
+            for (const dep of pkg.dependsOn) {
+                if (!known.has(dep) || dep === pkg.name)
+                    continue;
+                dependents.set(dep, [...dependents.get(dep) ?? [], pkg.name]);
+            }
+        }
+        const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
+        const out = [];
+        // Ready packages are taken in DECLARATION order, not in the order they became ready. Both are
+        // correct builds; only one is the same list every time and the same list a person wrote, and
+        // this order is compared against the shipped layout tables by a test.
+        const ready = packages.filter(pkg => pending.get(pkg.name) === 0).map(pkg => pkg.name);
+        const take = () => {
+            if (ready.length === 0)
+                return undefined;
+            let at = 0;
+            for (let i = 1; i < ready.length; i++) {
+                if ((index.get(ready[i]) ?? 0) < (index.get(ready[at]) ?? 0))
+                    at = i;
+            }
+            return ready.splice(at, 1)[0];
+        };
+        for (let name = take(); name != null; name = take()) {
+            const pkg = byName.get(name);
+            if (pkg == null)
+                continue;
+            out.push(pkg);
+            for (const next of dependents.get(name) ?? []) {
+                const left = (pending.get(next) ?? 0) - 1;
+                pending.set(next, left);
+                if (left === 0)
+                    ready.push(next);
+            }
+        }
+        const seen = new Set(out.map(pkg => pkg.name));
+        return [...out, ...packages.filter(pkg => !seen.has(pkg.name))];
+    };
+    const resolveTopology = (topology) => {
+        const ordered = orderPackages(topology.packages);
+        const byRole = {};
+        for (const pkg of ordered) {
+            for (const role of pkg.roles) {
+                byRole[role] = [...byRole[role] ?? [], pkg];
+            }
+        }
+        return {
+            ...topology,
+            packages: ordered,
+            build: ordered.map(pkg => pkg.name),
+            libraries: ordered.filter(pkg => pkg.kind === 'library').map(pkg => pkg.name),
+            byRole,
+        };
+    };
+    const topologyOf = (layout) => LAYOUT_TOPOLOGIES[layout] ?? DEFAULT_TOPOLOGY;
+    const packageForRole = (topology, role) => topology.byRole[role]?.[0] ?? null;
+    const packagesForRole = (topology, role) => topology.byRole[role] ?? [];
+    const packageForArea = (topology, role, area) => {
+        const candidates = packagesForRole(topology, role);
+        return candidates.find(pkg => pkg.areas?.includes(area) === true)
+            ?? candidates.find(pkg => pkg.areas == null)
+            ?? candidates[0]
+            ?? null;
+    };
+    const packageDir = (topology, pkg) => `${topology.dir}/${pkg.name}`;
+    const withPackage = (topology, pkg) => ({
+        ...topology,
+        packages: topology.packages.some(known => known.name === pkg.name)
+            ? topology.packages.map(known => known.name === pkg.name ? pkg : known)
+            : [...topology.packages, pkg],
+    });
+    const sameTopology = (a, b) => JSON.stringify(orderPackages(a.packages)) === JSON.stringify(orderPackages(b.packages))
+        && a.dir === b.dir;
+    return {
+        orderPackages, resolveTopology, topologyOf, packageForRole, packagesForRole, packageForArea, packageDir,
+        withPackage, sameTopology,
+    };
+};
+export const topologyHelper = createTopologyHelper();
+//# sourceMappingURL=resolve.js.map

package/build/topology/resolve.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/viable-common",
-  "version": "0.0.44",
+  "version": "0.0.45",
   "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, the connector protocol and the conversion vocabulary, and the intent-first hand-off from the public site to the platform.",
   "type": "module",
@@ -66,16 +66,16 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/agent-common": "^0.1.18-rc.47",
-    "@owlmeans/auth": "^0.1.18-rc.39",
-    "@owlmeans/context": "^0.1.18-rc.33",
-    "@owlmeans/entrypoint": "^0.1.18-rc.40",
-    "@owlmeans/error": "^0.1.18-rc.37",
-    "@owlmeans/flow": "^0.1.18-rc.44",
-    "@owlmeans/llm-common": "^0.1.18-rc.38",
-    "@owlmeans/planning": "^0.1.18-rc.18",
-    "@owlmeans/resource": "^0.1.18-rc.39",
-    "@owlmeans/route": "^0.1.18-rc.34"
+    "@owlmeans/agent-common": "^0.1.18-rc.48",
+    "@owlmeans/auth": "^0.1.18-rc.40",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/flow": "^0.1.18-rc.45",
+    "@owlmeans/llm-common": "^0.1.18-rc.39",
+    "@owlmeans/planning": "^0.1.18-rc.19",
+    "@owlmeans/resource": "^0.1.18-rc.40",
+    "@owlmeans/route": "^0.1.18-rc.35"
   },
   "publishConfig": {
     "access": "public"

package/src/agent/index.ts

@@ -1,5 +1,6 @@
 
 export type * from './types.js'
+export type * from './presentation/types.js'
 export * from './spectator/index.js'
 export * from './memory.js'
 export * from './presentation.js'

package/src/agent/presentation/types.ts

@@ -0,0 +1,21 @@
+import type { AgentCodeLanguage, AgentMessageRole } from '../consts.js'
+import type { AgentMessageClassificationInput, AgentMessagePresentation } from '../types.js'
+
+/** How an agent's thinking event is presented: its specialist family, its language, its card. */
+export interface AgentPresentationHelper {
+  /**
+   * 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.
+   */
+  isAgentMessageHidden: (input: AgentMessageClassificationInput) => boolean
+  /** Maps the attribution that reached the event boundary to the visual specialist family. */
+  agentMessageRoleOf: (input: AgentMessageClassificationInput) => AgentMessageRole
+  /** Pulls a schema argument out of LangChain's serialised tool-call shape. */
+  agentToolCallArguments: (value: unknown) => unknown
+  /** Finds the language of a unified diff from its destination (or source) file path. */
+  agentDiffLanguageOf: (text: string) => AgentCodeLanguage
+  /** Conservative code detection; prose with one identifier remains plain text. */
+  agentCodeLanguageOf: (text: string) => AgentCodeLanguage
+  isUnifiedDiff: (text: string) => boolean
+  classifyAgentMessage: (input: AgentMessageClassificationInput) => AgentMessagePresentation
+}