@owlmeans/agent 0.1.18-rc.7

package/build/stores/memory.d.ts

@@ -0,0 +1,6 @@
+import type { AgentRunStateStore, ConversationStore, MemoryEventStore, MemoryGraphStore } from './types.js';
+export declare const createMemoryConversationStore: () => ConversationStore;
+export declare const createMemoryGraphStore: () => MemoryGraphStore;
+export declare const createMemoryEventStore: () => MemoryEventStore;
+export declare const createMemoryRunStateStore: () => AgentRunStateStore;
+//# sourceMappingURL=memory.d.ts.map

package/build/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAC1E,MAAM,YAAY,CAAA;AAanB,eAAO,MAAM,6BAA6B,QAAO,iBAsBhD,CAAA;AAED,eAAO,MAAM,sBAAsB,QAAO,gBAqBzC,CAAA;AAED,eAAO,MAAM,sBAAsB,QAAO,gBA8BzC,CAAA;AAED,eAAO,MAAM,yBAAyB,QAAO,kBAO5C,CAAA"}

package/build/stores/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAQtD;;;;;;;GAOG;AAEH,MAAM,GAAG,GAAG,GAAW,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;AAElD,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAsB,EAAE;IACnE,MAAM,MAAM,GAAwB,EAAE,CAAA;IAEtC,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM;aAC/B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,cAAc,KAAK,GAAG,CAAC,cAAc,CAAC;aAC5D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;aAC7B,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAE/B,MAAM,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACpB,MAAM,GAAG,GAAG,MAAM;iBACf,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,cAAc,CAAC;iBAC9D,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;YAE1D,MAAM,KAAK,GAAsB;gBAC/B,GAAG,KAAK,EAAE,EAAE,EAAE,gBAAgB,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE;aAC7E,CAAA;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAElB,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAqB,EAAE;IAC3D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC3C,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,SAAiB,EAAU,EAAE,CAAC,GAAG,KAAK,IAAI,SAAS,EAAE,CAAA;IAEjF,OAAO;QACL,KAAK,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;aACtC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC;aACpC,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAE9E,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,IAAI,IAAI;QAE1E,KAAK,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;YAC7D,MAAM,IAAI,GAAe;gBACvB,GAAG,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,gBAAgB,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;aACrE,CAAA;YACD,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAA;YAElD,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAqB,EAAE;IAC3D,IAAI,MAAM,GAAkB,EAAE,CAAA;IAE9B,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM;aACjC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC;aACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;aAC7B,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAE/B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC7B,MAAM,GAAG,GAAG,MAAM;iBACf,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC;iBAC5C,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;YAE1D,MAAM,KAAK,GAAgB;gBACzB,GAAG,KAAK,EAAE,EAAE,EAAE,gBAAgB,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE;aAC7E,CAAA;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAElB,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBAC/B,uFAAuF;gBACvF,oFAAoF;gBACpF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;gBAC9F,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;gBACjE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;YACjF,CAAC;YAED,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAuB,EAAE;IAChE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAA;IAE/C,OAAO;QACL,IAAI,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI;QAC9C,IAAI,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC,CAAA,CAAC,CAAC;KACjG,CAAA;AACH,CAAC,CAAA"}

package/build/stores/types.d.ts

@@ -0,0 +1,38 @@
+import type { AgentRunState, ConversationEvent, ConversationEventInput, ConversationRef, MemoryEvent, MemoryEventInput, MemoryNode } from '@owlmeans/agent-common';
+/**
+ * Storage, as this package needs it.
+ *
+ * These are PORTS, not resources. The package could have taken `Resource<T>` and let a consumer
+ * register a backend under an alias — but `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. A port names what
+ * the plugin actually needs, which is a much smaller surface than CRUD, and any backend can
+ * satisfy it — including a file on disk, which is what the project-history equivalent is.
+ *
+ * Every port is optional to bind. A plugin whose port is missing degrades to a no-op rather than
+ * throwing, exactly as `ExecutionService.checkpoint` does with no plugin registered: memory is an
+ * enhancement, and an application that has not wired storage yet must still be able to run agents.
+ */
+export interface ConversationStore {
+    /** The most recent `limit` events, NEWEST FIRST. */
+    last: (ref: ConversationRef, limit: number) => Promise<ConversationEvent[]>;
+    /** Append one event, allocating its `seq`. */
+    append: (event: ConversationEventInput) => Promise<ConversationEvent>;
+}
+export interface MemoryGraphStore {
+    /** Every node of a scope, without its content — names and links only. */
+    index: (scope: string) => Promise<Array<Pick<MemoryNode, 'subsystem' | 'links' | 'updatedAt'>>>;
+    read: (scope: string, subsystem: string) => Promise<MemoryNode | null>;
+    write: (node: Omit<MemoryNode, 'id' | 'updatedAt'>) => Promise<MemoryNode>;
+}
+export interface MemoryEventStore {
+    /** The most recent `limit` events of a scope, NEWEST FIRST. */
+    read: (scope: string, limit: number) => Promise<MemoryEvent[]>;
+    /** Append one event, allocating its `seq`, and prune the scope to `limit` if given. */
+    append: (event: MemoryEventInput, limit?: number) => Promise<MemoryEvent>;
+}
+export interface AgentRunStateStore {
+    load: (runId: string) => Promise<AgentRunState | null>;
+    save: (state: AgentRunState) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/stores/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,eAAe,EACzE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAC1C,MAAM,wBAAwB,CAAA;AAE/B;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,IAAI,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAA;IAC3E,8CAA8C;IAC9C,MAAM,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACtE;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAC/F,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IACtE,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CAC3E;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IAC9D,uFAAuF;IACvF,MAAM,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;CAC1E;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IACtD,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C"}

package/build/stores/types.js

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

package/build/stores/types.js.map

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

package/build/types.d.ts

@@ -0,0 +1,130 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { AIMessage, BaseMessage, HumanMessage } from '@langchain/core/messages';
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { BasicConfig, BasicContext, InitializedService } from '@owlmeans/context';
+import type { FlowModel, FlowProvider, ShallowFlow } from '@owlmeans/flow';
+import type { Execution, LlmPlugin, ModelInputItem, PromptService } from '@owlmeans/llm';
+import type { AgentRunStatus, ConversationEvent, ConversationRef } from '@owlmeans/agent-common';
+import type { AgentTransport } from './runtime/transport.js';
+import type { ConversationStore } from './stores/types.js';
+/** Tools an agent may call, keyed however the caller likes — resolution is by `tool.name`. */
+export interface AgentToolSet {
+    [key: string]: StructuredToolInterface;
+}
+/**
+ * What the caller gets told about each model call.
+ *
+ * Shaped to match `spectate(spectator, callType)` from `@owlmeans/llm` exactly, so an application
+ * that already has a spectator passes the curried function straight in.
+ */
+export interface AgentSpectateHook {
+    (input: ModelInputItem[], message: AIMessage, action: string, retries: number, startedAt?: number): Promise<unknown>;
+}
+export interface AgentOptions {
+    /** The execution the run belongs to. Its `prompt` policy is the agent's persona. */
+    exec: Execution;
+    /** Overrides the model resolved from the execution. */
+    agentModel?: BaseChatModel;
+    tools: AgentToolSet;
+    /** Static volatile context. Lands in `PromptBlock.Context`, never in the cached prefix. */
+    context?: string[];
+    conversation?: ConversationRef;
+    /** LangGraph entrypoint name; shows up in traces. */
+    entrypoint?: string;
+    spectate?: AgentSpectateHook;
+    prompts?: () => PromptService;
+    /** Provider plugin used for cache placement. Resolved from the model when omitted. */
+    provider?: LlmPlugin;
+    maxTurns?: number;
+    /**
+     * Whether `invoke()` finalizes the run itself.
+     *
+     * Leave it on for a caller whose work ends when the model stops talking. Turn it OFF when
+     * something runs AFTER the agent that changes the outcome — a validation pass, a build — because
+     * a compaction written before that step describes a state that did not survive it, and the
+     * "what to do next" it produces is then advice about a world that no longer exists.
+     */
+    autoFinish?: boolean;
+    plugins?: AgentPlugin[];
+}
+export interface AgentInvokeArgs {
+    /** LangChain `runName` for the model calls of this run. */
+    action?: string;
+    /** Extra volatile context for this call only. */
+    context?: string[];
+}
+export interface AgentRunOutcome {
+    status: AgentRunStatus;
+    /** What happened after the loop — a fixer verdict, a build result. Reaches the compaction. */
+    note?: string;
+    error?: Error;
+}
+/** What a plugin sees. Deliberately carries no service: a model built standalone has none. */
+export interface AgentRun {
+    id: string;
+    conversation: ConversationRef;
+    exec: Execution;
+    flow: FlowModel;
+    /** The ask that opened the run. */
+    prompt: string;
+    action: string;
+}
+export interface AgentRunHandle {
+    id: string;
+    conversation: ConversationRef;
+    /** Fires `onFinish` on every plugin. Idempotent — a second call is a no-op, never a second event. */
+    finish: (outcome: AgentRunOutcome) => Promise<void>;
+}
+export interface AgentResult {
+    message: AIMessage;
+    /** The whole transcript of the run, the opening human message included. */
+    messages: BaseMessage[];
+    run: AgentRunHandle;
+}
+/**
+ * The package's own optional-capability seam.
+ *
+ * A plugin may contribute what an agent knows (`context`), what it can do (`tools`), watch it work
+ * (`onTurn`), and act when it stops (`onFinish`). Everything memory- and summary-related in this
+ * family is one of these; nothing in the loop itself knows those features exist.
+ */
+export interface AgentPlugin {
+    alias: string;
+    /** Lower runs first. Defaults to 50. */
+    order?: number;
+    context?: (run: AgentRun) => Promise<string[]>;
+    tools?: (run: AgentRun) => AgentToolSet;
+    onTurn?: (run: AgentRun, messages: readonly BaseMessage[]) => Promise<void>;
+    onFinish?: (run: AgentRun, result: AgentResult, outcome: AgentRunOutcome) => Promise<void>;
+}
+export interface AgentModel {
+    use: (plugin: AgentPlugin) => void;
+    invoke: (input: string | HumanMessage, args?: AgentInvokeArgs) => Promise<AgentResult>;
+    conversation: () => ConversationRef;
+}
+export interface ConversationApi {
+    last: (limit?: number) => Promise<ConversationEvent[]>;
+    append: (event: Omit<ConversationEvent, 'id' | 'seq' | 'createdAt'>) => Promise<ConversationEvent>;
+}
+export interface AgentServiceOptions {
+    /** Extra flows the provider should serve. The run lifecycle flow is always included. */
+    flows?: ShallowFlow[];
+    transport?: AgentTransport;
+    plugins?: AgentPlugin[];
+    conversations?: ConversationStore;
+}
+export interface AgentService extends InitializedService {
+    /** Build an agent with the service's plugins already attached. */
+    agent: (options: AgentOptions) => AgentModel;
+    use: (plugin: AgentPlugin) => void;
+    plugins: () => AgentPlugin[];
+    flow: FlowProvider;
+    transport: () => AgentTransport;
+    /** Conversation access for callers that want it outside a run. No store bound → empty results. */
+    conversation: (ref: ConversationRef) => ConversationApi;
+}
+export interface WithAgentsService {
+    agents: () => AgentService;
+}
+export type AgentContext<C extends BasicConfig = BasicConfig> = BasicContext<C> & WithAgentsService;
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

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

package/build/types.js

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

package/build/types.js.map

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@owlmeans/agent",
+  "version": "0.1.18-rc.7",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 178 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./plugins": {
+      "import": "./build/plugins/export.js",
+      "require": "./build/plugins/export.js",
+      "default": "./build/plugins/export.js",
+      "module": "./build/plugins/export.js",
+      "types": "./build/plugins/export.d.ts"
+    },
+    "./helpers": {
+      "import": "./build/helpers/index.js",
+      "require": "./build/helpers/index.js",
+      "default": "./build/helpers/index.js",
+      "module": "./build/helpers/index.js",
+      "types": "./build/helpers/index.d.ts"
+    },
+    "./stores": {
+      "import": "./build/stores/index.js",
+      "require": "./build/stores/index.js",
+      "default": "./build/stores/index.js",
+      "module": "./build/stores/index.js",
+      "types": "./build/stores/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.1.39",
+    "@langchain/langgraph": "^1.2.8",
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2",
+    "zod": "^4.1.0"
+  },
+  "dependencies": {
+    "@owlmeans/agent-common": "^0.1.18-rc.7",
+    "@owlmeans/basic-ids": "^0.1.18-rc.6",
+    "@owlmeans/context": "^0.1.18-rc.6",
+    "@owlmeans/error": "^0.1.18-rc.6",
+    "@owlmeans/flow": "^0.1.18-rc.6",
+    "@owlmeans/llm": "^0.1.18-rc.6",
+    "@owlmeans/llm-common": "^0.1.18-rc.6",
+    "ajv": "^8.17.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^1.1.39",
+    "@langchain/langgraph": "^1.2.8"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,19 @@
+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

package/src/errors.ts

@@ -0,0 +1,33 @@
+import { ResilientError } from '@owlmeans/error'
+
+export class AgentError extends ResilientError {
+  public static override typeName: string = `AgentRuntime${ResilientError.typeName}`
+
+  constructor(message: string = '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 {
+  public static override typeName: string = `Missconfigured${AgentError.typeName}`
+
+  constructor(message: string = '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 {
+  public static override typeName: string = `LoopExhausted${AgentError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`loop-exhausted:${message}`)
+    this.type = AgentLoopExhaustedError.typeName
+  }
+}
+
+ResilientError.registerErrorClass(AgentError)
+ResilientError.registerErrorClass(AgentMissconfiguredError)
+ResilientError.registerErrorClass(AgentLoopExhaustedError)

package/src/helpers/compaction.ts

@@ -0,0 +1,172 @@
+import type { BaseMessage } from '@langchain/core/messages'
+import type { JSONSchemaType } from 'ajv'
+import type { LlmModel } from '@owlmeans/llm'
+import { AgentRunStatus, DEFAULT_ADVICE_CHARS, DEFAULT_SUMMARY_CHARS, truncateAt } 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
+}
+
+const DEFAULT_TRANSCRIPT_CHARS = 24_000
+
+/** The text of a message, whatever content shape it arrived in. */
+export const messageText = (message: BaseMessage): string => {
+  const content = message.content
+  if (typeof content === 'string') {
+    return content
+  }
+  if (Array.isArray(content)) {
+    return content
+      .map(part => typeof part === 'string' ? part : (part as { text?: string }).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: readonly BaseMessage[], maxChars = DEFAULT_TRANSCRIPT_CHARS,
+): string => {
+  const lines: string[] = []
+  let used = 0
+
+  for (let i = messages.length - 1; i >= 0; --i) {
+    const message = messages[i]
+    const text = messageText(message).trim()
+    const calls = (message as { tool_calls?: Array<{ name: string }> }).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: JSONSchemaType<{ summary: string, advice: string }> = {
+  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: CompactionInput): Promise<Compaction> => {
+  const {
+    model, prompt, messages, status, note,
+    maxSummaryChars = DEFAULT_SUMMARY_CHARS,
+    maxAdviceChars = DEFAULT_ADVICE_CHARS,
+    action = 'agent-compaction',
+    maxTranscriptChars,
+  } = input
+
+  const fallback = (): Compaction => {
+    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<{ summary: string, advice: string }>(
+      `
+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()
+  }
+}

package/src/helpers/index.ts

@@ -0,0 +1,3 @@
+export * from './tools.js'
+export * from './compaction.js'
+export * from './rolling.js'

package/src/helpers/rolling.ts

@@ -0,0 +1,68 @@
+import type { LlmModel } from '@owlmeans/llm'
+import { truncateAt } from '@owlmeans/agent-common'
+
+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 const composeRollingSummary = async (input: RollingSummaryInput): Promise<string> => {
+  const { model, previous, event, details, maxChars, action = 'agent-rolling-summary' } = input
+
+  const trimmedPrevious = previous.trim()
+  const fallback = (): string => 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()
+  }
+}

package/src/helpers/tools.ts

@@ -0,0 +1,46 @@
+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 const toErrorResponse = (e: unknown): ToolErrorResponse =>
+  ({ error: `Error during tool call: ${(e instanceof Error) ? e.message : String(e)}` })
+
+export const isToolError = (result: unknown): result is ToolErrorResponse =>
+  typeof result === 'object' && result != null && 'error' in result
+
+/**
+ * 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 const safeInvokeTool = async (tools: AgentToolSet, toolCall: ToolCall): Promise<unknown> => {
+  const tool = tools[toolCall.name]
+    ?? Object.values(tools).find(entry => entry.name === toolCall.name)
+
+  if (tool == null) {
+    return toErrorResponse(new Error(`Tool ${toolCall.name} not found`))
+  }
+
+  try {
+    return await tool.invoke(toolCall.args)
+  } catch (e) {
+    console.warn(`Error during tool call ${toolCall.name}:`, e)
+    return toErrorResponse(e)
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './consts.js'
+export * from './errors.js'
+export type * from './types.js'
+export * from './model.js'
+export * from './service.js'
+export * from './helpers/index.js'
+export * from './stores/index.js'
+export * from './runtime/provider.js'
+export * from './runtime/transport.js'
+export * from './runtime/checkpoint.js'
+export * from './plugins/export.js'