@owlmeans/agent 0.1.18-rc.7

package/README.md

@@ -0,0 +1,93 @@
+# @owlmeans/agent
+
+Context-aware LLM agents and pipelines over the LangGraph functional API, with pluggable memory and
+storage-independent persistence.
+
+Contracts live in [`@owlmeans/agent-common`](../agent-common); LangGraph and LangChain core are
+**peer** dependencies.
+
+## Building an agent
+
+```ts
+import { makeAgentModel } from '@owlmeans/agent'
+
+const agent = makeAgentModel({
+  exec,                      // an @owlmeans/llm Execution — its prompt policy is the persona
+  tools,                     // { [name]: StructuredToolInterface }
+  context: [projectBrief],   // volatile context; lands in PromptBlock.Context
+})
+
+const result = await agent.invoke('rename the dashboard header')
+```
+
+Or through the context service, which pre-attaches the plugins registered on it:
+
+```ts
+import { appendAgentsService } from '@owlmeans/agent'
+
+appendAgentsService(context, { conversations, plugins: [summarizePlugin({ store })] })
+const agent = context.agents().agent({ exec, tools })
+```
+
+## Plugins
+
+`AgentPlugin` is the optional-capability seam: a plugin may contribute what the agent knows
+(`context`), what it can do (`tools`), watch it work (`onTurn`), and act when it stops (`onFinish`).
+
+| Plugin | What it adds |
+|---|---|
+| `summarizePlugin` | Compacts each finished run into `summary` + `advice`, and replays the last few on the way in |
+| `memoryGraphPlugin` | Durable notes filed by subsystem, with links — index injected, content pulled by tool |
+| `memoryEventsPlugin` | A bounded, ordered record of what happened |
+
+Both memory plugins also export a plain API (`memoryGraph`, `memoryEvents`) usable with no agent at
+all, so a pipeline helper writes to the same store an agent reads.
+
+## Things worth knowing before you change it
+
+**Contributed context goes to `PromptBlock.Context` and nowhere else.** That is the only block a
+provider will not put a cache breakpoint on. Volatile material anywhere above it invalidates the
+prefix that every call sharing a persona pays for.
+
+**`safeInvokeTool` must never throw.** A rejected LangGraph task aborts the whole superstep: every
+sibling tool call in the same parallel batch dies with it, discarding work they had already
+finished. A tool failure comes back as `{ error }` the model can read and correct.
+
+**Resolution is by `tool.name`, not by map key.** `bindTools` advertises the tool's own name, so a
+map keyed by a local variable silently loses any tool whose two names drifted apart — advertised,
+callable, and permanently "not found".
+
+**`autoFinish: false` when something runs after the agent.** A compaction written before a
+validation or build pass describes a state that did not survive it, so its "what to do next" is
+advice about a world that no longer exists. Call `result.run.finish(outcome)` once the real outcome
+is known; it is idempotent.
+
+**Plugin failures never fail a run.** Contributing, per-turn work and finalization are all
+swallowed with a warning. Memory is an enhancement; losing it costs context, throwing costs the work.
+
+**Ports, not resources.** `ConversationStore` and friends are narrow interfaces a consumer
+implements. An unbound port is not an error — the plugin that needs it becomes a no-op.
+
+**Give the compaction call a `runName` your application filters.** Every model call carrying a
+purpose is streamed to the client, so without it the summary of a run types itself out in the
+user's view of that run, right after it finished.
+
+**No LangGraph checkpointer.** Recoverability lives in the OwlMeans execution and flow layers, which
+already own a serializable state model; `makeAgentExecutionPlugin` is the first real implementation
+of `@owlmeans/llm`'s `ExecutionPlugin` seam.
+
+<!-- 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
+```
+
+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,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/agent",
+  "version": "0.1.18-rc.7",
+  "generatedAt": "2026-08-27T21:09:58.916Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "agent",
+      "category": "package-specific",
+      "file": "skills/agent/SKILL.md",
+      "canonicalPath": ".agents/skills/agent/SKILL.md"
+    }
+  ]
+}

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

@@ -0,0 +1,122 @@
+---
+name: agent
+description: How to use @owlmeans/agent — context-aware LLM agents and pipelines over the LangGraph functional API, with the AgentPlugin seam, conversation-summarization and memory plugins, storage-independent ports, and the ExecutionPlugin checkpoint implementation. Auto-invoked when importing makeAgentModel, appendAgentsService, an agent plugin, safeInvokeTool, or an agent store.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/agent
+
+**Layer:** Cross-cutting domain
+**Install:** `"@owlmeans/agent": "^0.1.18-rc.7"` in `dependencies`, plus the `@langchain/core` and
+`@langchain/langgraph` **peers**
+
+The agent runtime. Contracts live in `@owlmeans/agent-common`.
+
+## Key exports
+
+| Export | Description |
+|---|---|
+| `makeAgentModel(options)` | An agent over the LangGraph functional API: `invoke`, `use`, `conversation`. |
+| `makeAgentsService(options?, alias?)` · `appendAgentsService(ctx, options?, alias?)` · `agentServiceApi(options, self)` | The service, and its half without `createService` for composition. |
+| `summarizePlugin(options?)` | Compacts each finished run into `summary` + `advice`; replays the last few. |
+| `memoryGraphPlugin(options?)` · `memoryGraph(store, options?)` | Durable notes filed by subsystem, with links. Plugin **and** plain API. |
+| `memoryEventsPlugin(options?)` · `memoryEvents(store, options?)` | A bounded, ordered record of what happened. |
+| `safeInvokeTool`, `toErrorResponse`, `isToolError` | The never-throwing tool contract. |
+| `composeCompaction`, `composeRollingSummary`, `renderTranscript`, `messageText` | Summary primitives; both composers are total. |
+| `makeAgentExecutionPlugin(options)` | The first real implementation of `@owlmeans/llm`'s `ExecutionPlugin`. |
+| `makeStaticFlowProvider(flows)` | The server-side `FlowProvider` `@owlmeans/flow` never shipped. |
+| `inProcessTransport()`, `AgentTransport` | The scaling seam; default carries messages by direct call. |
+| `createMemory*Store()` | In-memory reference implementations of every port. |
+
+Subpath exports: `./plugins`, `./helpers`, `./stores`.
+
+## The plugin seam
+
+```ts
+interface AgentPlugin {
+  alias: string
+  order?: number                                   // lower first, default 50
+  context?: (run) => Promise<string[]>             // what the agent knows
+  tools?: (run) => AgentToolSet                    // what it can do
+  onTurn?: (run, messages) => Promise<void>        // watch it work
+  onFinish?: (run, result, outcome) => Promise<void> // act when it stops
+}
+```
+
+Registered with `agent.use(plugin)` or `service.use(plugin)`; seated **by alias**, so re-registering
+replaces rather than duplicating. Everything memory- and summary-related is one of these; the loop
+itself does not know those features exist.
+
+## Rules
+
+**Contributed context goes to `PromptBlock.Context` and nowhere else.** It is the only block a
+provider will not put a cache breakpoint on — the Anthropic plugin explicitly refuses to mark a
+trailing `Context`. Volatile material anywhere above it invalidates the `Role` + `Skills` prefix
+that every call sharing a persona pays for.
+
+**`safeInvokeTool` must never throw.** The loop wraps it in a LangGraph `task`, and a rejected task
+aborts the whole superstep: every sibling tool call in the same parallel batch dies with AbortError
+and the run ends on "Multiple errors occurred during superstep 0", discarding work the others had
+already finished. A tool failure comes back as `{ error }` the model can read and correct — most are
+the model's own mistake, and the error text already names what was expected.
+
+**Tools resolve by `tool.name`, with the map key as a fallback.** `bindTools` advertises the tool's
+own name, so a map keyed by a local variable silently loses any tool whose two names drifted apart:
+advertised, callable, permanently "not found".
+
+**`compose()` is called with `files: exec.files`.** Without it, a prompt plugin that resolves
+knowledge from disk is silently inert on agent runs while working fine on plain model calls.
+
+**Use `autoFinish: false` whenever something runs after the agent.** A compaction written before a
+validation or build pass describes a state that did not survive it, so its "what to do next" is
+advice about a world that no longer exists. Call `result.run.finish(outcome)` once the real outcome
+is known — it is idempotent, and a second call is a no-op rather than a second event.
+
+**A failed run is still reported to `onFinish` before the error is rethrown.** A run that vanishes
+from the history is one the next session repeats verbatim.
+
+**Plugin failures never fail a run.** Contributing, per-turn work and finalization are each
+swallowed with a warning. Memory is an enhancement: losing it costs context, throwing costs the work.
+
+**Give the compaction call a `runName` the application filters.** Every model call carrying a purpose
+is streamed to the client, so without it the summary of a run types itself out in the user's view of
+that run, immediately after it finished.
+
+**Character caps are applied after the model answers, never asked for in the prompt alone.** A cap in
+a prompt is a request. Both composers (`composeCompaction`, `composeRollingSummary`) are total: with
+no model, a failing model or an empty answer they fall back deterministically, so a caller can record
+history unconditionally. A failed fold costs detail, never the event.
+
+**Ports, not resources.** `ConversationStore`, `MemoryGraphStore`, `MemoryEventStore` and
+`AgentRunStateStore` are narrow interfaces a consumer implements. `Resource.list()` is not uniformly
+queryable — `@owlmeans/static-resource` throws on any criteria — so a plugin written against its
+query semantics could not be exercised with the monorepo's own in-memory backend. An unbound port is
+a no-op, not an error.
+
+**Memory writes merge, they do not replace.** Replacing would make every write a potential act of
+forgetting, which is not a decision one caller has the standing to take. A node that outgrows
+`maxNodeChars` is compacted through the cheap model, or head-truncated when there is none.
+
+**Only the memory INDEX is injected — names and links, never content.** Bulk-injecting notes spends
+the context window on knowledge the run cannot tell apart from what it needs; the agent pulls what it
+wants by name.
+
+**Checkpoints are size-guarded.** A project-level execution carries the whole project specification;
+writing that on every checkpoint is a storage problem that surfaces much later and much worse than a
+skipped write.
+
+**No LangGraph checkpointer, and the `entrypoint` is created inside `invoke()`.** Recoverability
+lives in the OwlMeans execution and flow layers, which already own a serializable state model;
+adopting a second one would leave two half-truths about where a crashed run stands.
+
+**`makeStaticFlowProvider` must throw on an unknown flow.** `makeFlowModel` reads a string as a flow
+name first and only re-reads it as a serialized token once the provider throws — returning null
+would break every restore.
+
+## Testing
+
+Category A (unit, no env, no network). The model is doubled with a small scripted object in
+`tests/_tools/model.ts` because `@langchain/core`'s own `FakeStreamingChatModel` always replays its
+first response and so cannot drive a tool loop. That double stands in for the MODEL, an external
+boundary — never for an `@owlmeans/*` package.

package/build/consts.d.ts

@@ -0,0 +1,16 @@
+export { AGENTS_SERVICE } from '@owlmeans/agent-common';
+/** Default LangGraph entrypoint name. Shows up in traces, so it is worth overriding per agent. */
+export declare const DEFAULT_ENTRYPOINT = "owlmeans-agent";
+/** Default action label for a model call, used as the LangChain `runName`. */
+export declare const DEFAULT_ACTION = "agent-ask";
+/**
+ * How many tool rounds one run may take before it is stopped.
+ *
+ * A model that keeps calling tools without ever answering is not rare — it is the ordinary failure
+ * mode of a loop whose tool results do not satisfy it. Without a ceiling the run consumes the
+ * caller's budget until something else kills it, which reads as a hang rather than a refusal.
+ */
+export declare const DEFAULT_MAX_TURNS = 64;
+/** Ordering weight of a plugin that declares none. */
+export declare const DEFAULT_PLUGIN_ORDER = 50;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEvD,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,mBAAmB,CAAA;AAElD,8EAA8E;AAC9E,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,KAAK,CAAA"}

package/build/consts.js

@@ -0,0 +1,16 @@
+export { AGENTS_SERVICE } from '@owlmeans/agent-common';
+/** Default LangGraph entrypoint name. Shows up in traces, so it is worth overriding per agent. */
+export const DEFAULT_ENTRYPOINT = 'owlmeans-agent';
+/** Default action label for a model call, used as the LangChain `runName`. */
+export const DEFAULT_ACTION = 'agent-ask';
+/**
+ * How many tool rounds one run may take before it is stopped.
+ *
+ * A model that keeps calling tools without ever answering is not rare — it is the ordinary failure
+ * mode of a loop whose tool results do not satisfy it. Without a ceiling the run consumes the
+ * caller's budget until something else kills it, which reads as a hang rather than a refusal.
+ */
+export const DEFAULT_MAX_TURNS = 64;
+/** Ordering weight of a plugin that declares none. */
+export const DEFAULT_PLUGIN_ORDER = 50;
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEvD,kGAAkG;AAClG,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAA;AAElD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAEnC,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,16 @@
+import { ResilientError } from '@owlmeans/error';
+export declare class AgentError extends ResilientError {
+    static typeName: string;
+    constructor(message?: string);
+}
+/** The agent was built without something it cannot work around — a model, or a tool set. */
+export declare class AgentMissconfiguredError extends AgentError {
+    static typeName: string;
+    constructor(message?: string);
+}
+/** The tool loop hit its turn ceiling without the model ever answering. */
+export declare class AgentLoopExhaustedError extends AgentError {
+    static typeName: string;
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,UAAW,SAAQ,cAAc;IAC5C,OAAuB,QAAQ,EAAE,MAAM,CAA2C;IAElF,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED,4FAA4F;AAC5F,qBAAa,wBAAyB,SAAQ,UAAU;IACtD,OAAuB,QAAQ,EAAE,MAAM,CAAyC;IAEhF,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,2EAA2E;AAC3E,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,OAAuB,QAAQ,EAAE,MAAM,CAAwC;IAE/E,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF"}

package/build/errors.js

@@ -0,0 +1,27 @@
+import { ResilientError } from '@owlmeans/error';
+export class AgentError extends ResilientError {
+    static typeName = `AgentRuntime${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(AgentError.typeName, `agent-runtime:${message}`);
+    }
+}
+/** The agent was built without something it cannot work around — a model, or a tool set. */
+export class AgentMissconfiguredError extends AgentError {
+    static typeName = `Missconfigured${AgentError.typeName}`;
+    constructor(message = 'error') {
+        super(`missconfigured:${message}`);
+        this.type = AgentMissconfiguredError.typeName;
+    }
+}
+/** The tool loop hit its turn ceiling without the model ever answering. */
+export class AgentLoopExhaustedError extends AgentError {
+    static typeName = `LoopExhausted${AgentError.typeName}`;
+    constructor(message = 'error') {
+        super(`loop-exhausted:${message}`);
+        this.type = AgentLoopExhaustedError.typeName;
+    }
+}
+ResilientError.registerErrorClass(AgentError);
+ResilientError.registerErrorClass(AgentMissconfiguredError);
+ResilientError.registerErrorClass(AgentLoopExhaustedError);
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,UAAW,SAAQ,cAAc;IACrC,MAAM,CAAU,QAAQ,GAAW,eAAe,cAAc,CAAC,QAAQ,EAAE,CAAA;IAElF,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,iBAAiB,OAAO,EAAE,CAAC,CAAA;IACxD,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,OAAO,wBAAyB,SAAQ,UAAU;IAC/C,MAAM,CAAU,QAAQ,GAAW,iBAAiB,UAAU,CAAC,QAAQ,EAAE,CAAA;IAEhF,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,QAAQ,CAAA;IAC/C,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,uBAAwB,SAAQ,UAAU;IAC9C,MAAM,CAAU,QAAQ,GAAW,gBAAgB,UAAU,CAAC,QAAQ,EAAE,CAAA;IAE/E,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC,QAAQ,CAAA;IAC9C,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAA;AAC7C,cAAc,CAAC,kBAAkB,CAAC,wBAAwB,CAAC,CAAA;AAC3D,cAAc,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAA"}

package/build/helpers/compaction.d.ts

@@ -0,0 +1,46 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { LlmModel } from '@owlmeans/llm';
+import { AgentRunStatus } from '@owlmeans/agent-common';
+export interface Compaction {
+    summary: string;
+    advice?: string;
+}
+export interface CompactionInput {
+    /** Omit to skip the model entirely and take the deterministic path. */
+    model?: LlmModel;
+    /** The ask that opened the run. */
+    prompt: string;
+    messages: readonly BaseMessage[];
+    status: AgentRunStatus;
+    /** What happened after the loop — a validation verdict, a build result. */
+    note?: string;
+    maxSummaryChars?: number;
+    maxAdviceChars?: number;
+    /** LangChain `runName`. Give it a value the application filters, or the summary of a run streams into the user's view of that run. */
+    action?: string;
+    /** How much of the transcript to show the model. */
+    maxTranscriptChars?: number;
+}
+/** The text of a message, whatever content shape it arrived in. */
+export declare const messageText: (message: BaseMessage) => string;
+/**
+ * A transcript the model can read, newest-biased.
+ *
+ * The tail is what matters to a compaction — how the run ENDED decides what to do next — so when
+ * the budget binds it is the head that goes.
+ */
+export declare const renderTranscript: (messages: readonly BaseMessage[], maxChars?: number) => string;
+/**
+ * Compact a finished run into what the next one needs.
+ *
+ * Two parts, deliberately. A summary alone leaves the next run to re-derive the plan from the
+ * outcome, which is where it invents a different one; the advice is the half that carries intent
+ * across the gap.
+ *
+ * **Never throws, and never trusts the model's arithmetic.** The character caps are applied after
+ * the answer comes back, because a cap in a prompt is a request. When the model is absent or fails
+ * — an exhausted budget is the common case, and asking again would fail the same way — the
+ * deterministic fallback still produces a usable event: what was asked, and how it ended.
+ */
+export declare const composeCompaction: (input: CompactionInput) => Promise<Compaction>;
+//# sourceMappingURL=compaction.d.ts.map

package/build/helpers/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/helpers/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,cAAc,EAA2D,MAAM,wBAAwB,CAAA;AAEhH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;IAChC,MAAM,EAAE,cAAc,CAAA;IACtB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sIAAsI;IACtI,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAID,mEAAmE;AACnE,eAAO,MAAM,WAAW,YAAa,WAAW,KAAG,MAalD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,aACjB,SAAS,WAAW,EAAE,wBAC/B,MA0BF,CAAA;AAYD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,UAAiB,eAAe,KAAG,OAAO,CAAC,UAAU,CAoElF,CAAA"}

package/build/helpers/compaction.js

@@ -0,0 +1,119 @@
+import { AgentRunStatus, DEFAULT_ADVICE_CHARS, DEFAULT_SUMMARY_CHARS, truncateAt } from '@owlmeans/agent-common';
+const DEFAULT_TRANSCRIPT_CHARS = 24_000;
+/** The text of a message, whatever content shape it arrived in. */
+export const messageText = (message) => {
+    const content = message.content;
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        return content
+            .map(part => typeof part === 'string' ? part : part.text ?? '')
+            .filter(text => text !== '')
+            .join('\n');
+    }
+    return '';
+};
+/**
+ * A transcript the model can read, newest-biased.
+ *
+ * The tail is what matters to a compaction — how the run ENDED decides what to do next — so when
+ * the budget binds it is the head that goes.
+ */
+export const renderTranscript = (messages, maxChars = DEFAULT_TRANSCRIPT_CHARS) => {
+    const lines = [];
+    let used = 0;
+    for (let i = messages.length - 1; i >= 0; --i) {
+        const message = messages[i];
+        const text = messageText(message).trim();
+        const calls = message.tool_calls;
+        const body = text !== ''
+            ? text
+            : calls != null && calls.length > 0
+                ? `(called ${calls.map(call => call.name).join(', ')})`
+                : '';
+        if (body === '') {
+            continue;
+        }
+        const line = `${message.getType()}: ${body}`;
+        if (used + line.length > maxChars) {
+            break;
+        }
+        lines.unshift(line);
+        used += line.length;
+    }
+    return lines.join('\n\n');
+};
+const COMPACTION_SCHEMA = {
+    type: 'object',
+    properties: {
+        summary: { type: 'string' },
+        advice: { type: 'string' },
+    },
+    required: ['summary', 'advice'],
+    additionalProperties: false,
+};
+/**
+ * Compact a finished run into what the next one needs.
+ *
+ * Two parts, deliberately. A summary alone leaves the next run to re-derive the plan from the
+ * outcome, which is where it invents a different one; the advice is the half that carries intent
+ * across the gap.
+ *
+ * **Never throws, and never trusts the model's arithmetic.** The character caps are applied after
+ * the answer comes back, because a cap in a prompt is a request. When the model is absent or fails
+ * — an exhausted budget is the common case, and asking again would fail the same way — the
+ * deterministic fallback still produces a usable event: what was asked, and how it ended.
+ */
+export const composeCompaction = async (input) => {
+    const { model, prompt, messages, status, note, maxSummaryChars = DEFAULT_SUMMARY_CHARS, maxAdviceChars = DEFAULT_ADVICE_CHARS, action = 'agent-compaction', maxTranscriptChars, } = input;
+    const fallback = () => {
+        const last = [...messages].reverse().find(message => messageText(message).trim() !== '');
+        const tail = last != null ? messageText(last).trim() : '';
+        const head = `Asked: ${prompt.trim()}`;
+        const ended = status === AgentRunStatus.Ok ? 'Finished.' : 'Did not finish.';
+        return {
+            summary: truncateAt([head, ended, note?.trim(), tail].filter(part => part != null && part !== '').join(' '), maxSummaryChars),
+        };
+    };
+    if (model == null) {
+        return fallback();
+    }
+    try {
+        const result = await model.invoke(`
+Compact the conversation below into a handover for the next session working on the same subject.
+
+Write two things:
+
+- summary: what was asked, what was actually done, and how it ended. Facts only — name the files,
+  decisions and failures that occurred. At most ${maxSummaryChars} characters.
+- advice: what the next session should do first, and what it should not repeat. If the work
+  finished cleanly, say what remains or say that nothing does. At most ${maxAdviceChars} characters.
+
+Write for a reader who cannot see this conversation and will act on your words alone. Do not
+address the reader, do not describe the conversation as a conversation, and do not speculate about
+anything not shown.
+
+# The ask that opened the session
+${prompt}
+
+# How it ended
+${status === AgentRunStatus.Ok ? 'Completed' : 'Failed'}${note != null && note !== '' ? ` — ${note}` : ''}
+
+# Conversation
+${renderTranscript(messages, maxTranscriptChars)}
+      `, COMPACTION_SCHEMA, { action });
+        const summary = truncateAt(result.summary ?? '', maxSummaryChars);
+        const advice = truncateAt(result.advice ?? '', maxAdviceChars);
+        // An empty summary is a non-answer, not a short one — take the deterministic path rather than
+        // storing a blank event that the next run will read as "nothing happened".
+        return summary === ''
+            ? fallback()
+            : { summary, ...(advice !== '' ? { advice } : {}) };
+    }
+    catch (e) {
+        console.warn('Agent compaction failed, falling back to a deterministic summary:', e);
+        return fallback();
+    }
+};
+//# sourceMappingURL=compaction.js.map

package/build/helpers/compaction.js.map

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

package/build/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export * from './tools.js';
+export * from './compaction.js';
+export * from './rolling.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/build/helpers/index.js

@@ -0,0 +1,4 @@
+export * from './tools.js';
+export * from './compaction.js';
+export * from './rolling.js';
+//# sourceMappingURL=index.js.map

package/build/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/build/helpers/rolling.d.ts

@@ -0,0 +1,25 @@
+import type { LlmModel } from '@owlmeans/llm';
+export interface RollingSummaryInput {
+    /** Omit to skip the model and take the deterministic path. */
+    model?: LlmModel;
+    /** The prose account so far. Empty on the first fold. */
+    previous: string;
+    /** What just happened, as one line. */
+    event: string;
+    /** Anything the fold may use but that need not survive into the summary. */
+    details?: string;
+    /** Hard ceiling on the returned prose, in characters. */
+    maxChars: number;
+    /** LangChain `runName`. Give it a value the application filters out of its user-facing stream. */
+    action?: string;
+}
+/**
+ * Fold one event into a running account of a subject, under a hard character ceiling.
+ *
+ * **Never throws.** When the model is unavailable or refuses, the previous prose is kept and
+ * head-truncated to make room rather than being replaced by an error or dropped: the caller's own
+ * verbatim record of the event is what preserves the fact, so a failed fold costs detail, never
+ * the event itself. That is the property that lets a caller record history unconditionally.
+ */
+export declare const composeRollingSummary: (input: RollingSummaryInput) => Promise<string>;
+//# sourceMappingURL=rolling.d.ts.map

package/build/helpers/rolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolling.d.ts","sourceRoot":"","sources":["../../src/helpers/rolling.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG7C,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,UAAiB,mBAAmB,KAAG,OAAO,CAAC,MAAM,CAyCtF,CAAA"}

package/build/helpers/rolling.js

@@ -0,0 +1,45 @@
+import { truncateAt } from '@owlmeans/agent-common';
+/**
+ * Fold one event into a running account of a subject, under a hard character ceiling.
+ *
+ * **Never throws.** When the model is unavailable or refuses, the previous prose is kept and
+ * head-truncated to make room rather than being replaced by an error or dropped: the caller's own
+ * verbatim record of the event is what preserves the fact, so a failed fold costs detail, never
+ * the event itself. That is the property that lets a caller record history unconditionally.
+ */
+export const composeRollingSummary = async (input) => {
+    const { model, previous, event, details, maxChars, action = 'agent-rolling-summary' } = input;
+    const trimmedPrevious = previous.trim();
+    const fallback = () => trimmedPrevious === ''
+        ? truncateAt(event, maxChars)
+        : truncateAt(trimmedPrevious, maxChars);
+    if (model == null) {
+        return fallback();
+    }
+    try {
+        const result = await model.ask(`
+Update the running account of a project with the event below.
+
+Write ONE account that covers the project's whole life so far, at most ${maxChars} characters. Keep
+what still matters — what the project is, the decisions taken, what has been built, what failed and
+was not repaired. Drop detail that later events made irrelevant. Prefer losing old detail to losing
+recent facts.
+
+Facts only. No preamble, no headings, no addressing the reader, no speculation about what happens
+next. Plain prose paragraphs.
+
+# The account so far
+${trimmedPrevious === '' ? '(nothing recorded yet)' : trimmedPrevious}
+
+# What just happened
+${event}${details != null && details !== '' ? `\n\n# Detail\n${details}` : ''}
+      `, { action });
+        const summary = truncateAt(result ?? '', maxChars);
+        return summary === '' ? fallback() : summary;
+    }
+    catch (e) {
+        console.warn('Rolling summary fold failed, keeping the previous account:', e);
+        return fallback();
+    }
+};
+//# sourceMappingURL=rolling.js.map

package/build/helpers/rolling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolling.js","sourceRoot":"","sources":["../../src/helpers/rolling.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAiBnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EAAE,KAA0B,EAAmB,EAAE;IACzF,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,EAAE,GAAG,KAAK,CAAA;IAE7F,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;IACvC,MAAM,QAAQ,GAAG,GAAW,EAAE,CAAC,eAAe,KAAK,EAAE;QACnD,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC7B,CAAC,CAAC,UAAU,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAA;IAEzC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,QAAQ,EAAE,CAAA;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAC5B;;;yEAGmE,QAAQ;;;;;;;;;EAS/E,eAAe,KAAK,EAAE,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,eAAe;;;EAGnE,KAAK,GAAG,OAAO,IAAI,IAAI,IAAI,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,iBAAiB,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE;OACtE,EACD,EAAE,MAAM,EAAE,CACX,CAAA;QAED,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAA;QAElD,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,OAAO,CAAA;IAC9C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,4DAA4D,EAAE,CAAC,CAAC,CAAA;QAC7E,OAAO,QAAQ,EAAE,CAAA;IACnB,CAAC;AACH,CAAC,CAAA"}

package/build/helpers/tools.d.ts

@@ -0,0 +1,29 @@
+import type { ToolCall } from '@langchain/core/messages';
+import type { AgentToolSet } from '../types.js';
+/** The shape a contained tool failure comes back as. Matches what tool bodies return themselves. */
+export interface ToolErrorResponse {
+    error: string;
+}
+export declare const toErrorResponse: (e: unknown) => ToolErrorResponse;
+export declare const isToolError: (result: unknown) => result is ToolErrorResponse;
+/**
+ * Run one model-requested tool, contained.
+ *
+ * **Never throws.** The caller wraps this in a LangGraph task, and a rejected task aborts the whole
+ * superstep: every sibling tool call in the same parallel batch dies with AbortError and the run
+ * ends on "Multiple errors occurred during superstep 0", discarding work the other calls had
+ * already finished. A tool failure has to come back as something the model can read and correct
+ * instead — most of them are the model's own mistake (an argument outside an enum, a hallucinated
+ * tool name), and the error text already names what was expected.
+ *
+ * Awaiting `invoke` is what makes the catch reachable: the tool's schema is validated inside it, so
+ * a bad argument rejects asynchronously and returning the promise unawaited would carry the
+ * rejection straight past this handler.
+ *
+ * Resolution is by the tool's OWN name, not by the map key. `bindTools` advertises `tool.name`, so
+ * that is what the model calls — a map keyed by a local variable silently loses any tool whose two
+ * names drifted apart, leaving it advertised, callable, and permanently "not found". The key stays
+ * as a fallback so a caller may still address a tool by it.
+ */
+export declare const safeInvokeTool: (tools: AgentToolSet, toolCall: ToolCall) => Promise<unknown>;
+//# sourceMappingURL=tools.d.ts.map

package/build/helpers/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/helpers/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAAG,KAAK,EAAE,MAAM,CAAA;CAAE;AAEpD,eAAO,MAAM,eAAe,MAAO,OAAO,KAAG,iBAC2C,CAAA;AAExF,eAAO,MAAM,WAAW,WAAY,OAAO,KAAG,MAAM,IAAI,iBACW,CAAA;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,UAAiB,YAAY,YAAY,QAAQ,KAAG,OAAO,CAAC,OAAO,CAc7F,CAAA"}