@owlmeans/agent-common 0.1.18-rc.7

package/README.md

@@ -0,0 +1,55 @@
+# @owlmeans/agent-common
+
+Serializable contracts for OwlMeans agents and LLM pipelines: conversation identity, the run
+lifecycle flow, and the record shapes an application persists.
+
+Runtime-free by design — no LangChain, no LangGraph, no storage driver. A backend or a browser
+bundle can import these shapes to read what an agent wrote without pulling the runtime. The
+runtime is [`@owlmeans/agent`](../agent).
+
+## What is here
+
+| Export | Purpose |
+|---|---|
+| `conversationFor(purpose, override?)` | Derives a `ConversationRef` from an `LlmPurpose` dedication — the thread identity an agent run belongs to |
+| `truncateAt(text, max)` | Boundary-aware truncation; every character cap in the family lands here |
+| `agentRunFlow` / `AgentRunStep` / `AgentRunTransition` | The `@owlmeans/flow` lifecycle a run is driven through |
+| `ConversationEvent` | One finished run, compacted: `summary` (what happened) + `advice` (what to do next) |
+| `AgentRunState` | The data plane of a run — serialized flow plus the execution snapshot |
+| `MemoryNode` / `MemoryEvent` | Agent-authored memory: a subsystem graph node, and an entry in a bounded sequence |
+| `AgentRunMessage` | What a transport carries; execution state travels by reference |
+
+## Conventions worth knowing
+
+**Timestamps are ISO strings, never `Date`.** These contracts cross process boundaries and storage
+backends and must survive `JSON.stringify` unchanged. A store whose backend prefers dates converts
+at its own adapter boundary.
+
+**Flow steps are lifecycle stages, not conversational turns.** `FlowPayload` holds flat scalars
+only and a ReAct loop's turn count is unbounded, so the loop lives inside the `Working` step and
+only its counter travels in the payload. What the steps buy is the ability to say where an
+interrupted run resumes.
+
+**Each working step has exactly one non-explicit outgoing transition**, so `FlowModel.next()` always
+has an unambiguous answer and a driver can advance a run without knowing the vocabulary. `Fail` is
+marked explicit precisely so it never becomes that automatic answer.
+
+**Port names are exported, ports are not bound here.** `AGENT_CONVERSATION_STORE` and friends are
+the keys a consumer registers its own storage under. An unbound port is not an error — the plugin
+that needs it degrades to a no-op.
+
+<!-- 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-common",
+  "version": "0.1.18-rc.7",
+  "generatedAt": "2026-08-27T21:09:58.915Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "agent-common",
+      "category": "package-specific",
+      "file": "skills/agent-common/SKILL.md",
+      "canonicalPath": ".agents/skills/agent-common/SKILL.md"
+    }
+  ]
+}

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

@@ -0,0 +1,66 @@
+---
+name: agent-common
+description: How to use @owlmeans/agent-common — runtime-free contracts for OwlMeans agents: conversation identity, the run-lifecycle flow, and the record shapes an application persists (conversation events, run state, memory nodes and events). Auto-invoked when importing agent record types, conversationFor, truncateAt, or the agent run flow.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/agent-common
+
+**Layer:** Cross-cutting domain
+**Install:** `"@owlmeans/agent-common": "^0.1.18-rc.7"` in `dependencies`
+
+Serializable contracts for the agent family. No LangChain, no LangGraph, no storage driver — a
+backend or a browser bundle imports these to read what an agent wrote without pulling the runtime.
+The runtime is `@owlmeans/agent`.
+
+## Key exports
+
+| Export | Description |
+|---|---|
+| `conversationFor(purpose, override?)` | Derives a `ConversationRef` from an `LlmPurpose` dedication. |
+| `truncateAt(text, max)` | Boundary-aware truncation. Every character cap in the family lands here. |
+| `agentRunFlow`, `AgentRunStep`, `AgentRunTransition`, `AGENT_RUN_FLOW` | The `@owlmeans/flow` lifecycle a run is driven through. |
+| `agentFlows` | Every flow this package declares, for a provider to serve. |
+| `ConversationEvent`, `ConversationEventInput` | One finished run, compacted: `summary` + `advice`. |
+| `AgentRunState` | Serialized flow plus the execution snapshot — the data plane of a run. |
+| `MemoryNode`, `MemoryEvent` (+ `MemoryEventInput`) | Agent-authored memory records. |
+| `AgentRunMessage` | What a transport carries; execution state travels by reference. |
+| `AGENTS_SERVICE` | The service alias — **`agents`**, plural. |
+| `AGENT_*_STORE` | Port names a consumer binds its storage under. |
+| `AgentRunStatus` | `ok` / `failed`, written on a conversation event. |
+| `AgentCommonError`, `AgentRunStateError` | The error family. |
+
+## Rules
+
+**Timestamps are ISO strings, never `Date`.** These contracts cross process boundaries and storage
+backends and must survive `JSON.stringify` unchanged. A store whose backend prefers dates converts
+at its own adapter boundary — that is the adapter's job, not the contract's.
+
+**The service alias is `agents`, and the accessor is `ctx.agents()`.** Plural and deliberately not
+`agent`: a consuming application very often already has a service of its own called that, and a
+context accessor collision is silent — the second registration simply wins.
+
+**Flow steps are lifecycle stages, not conversational turns.** `FlowPayload` holds flat scalars only
+and a ReAct loop's turn count is unbounded, so the loop lives inside the `Working` step and only its
+counter travels in the payload. What the steps buy is knowing where an interrupted run resumes:
+`Working` from the last checkpoint, or `Finalizing` when the loop finished but the compaction never
+committed.
+
+**Each working step keeps exactly one non-explicit outgoing transition.** That is what lets
+`FlowModel.next()` give a driver an unambiguous answer without knowing the vocabulary. `Fail` is
+marked `explicit` precisely so it can never become that automatic answer. Adding a second automatic
+edge to any step breaks `next()` for that step.
+
+**A conversation id degrades to a named default, never to an empty string.** An empty key would
+silently collapse every run of every subject into one thread.
+
+**Port names are exported; ports are not bound here.** An unbound port is not an error — the plugin
+that needs it degrades to a no-op, the way `ExecutionService.checkpoint` does with no plugin
+registered.
+
+## Testing
+
+Category A (unit, no env, no network). This package's own `tests/flow.spec.ts` covers the flow
+round-trip — which is also the standing check that `@owlmeans/flow` still works server-side, since
+every other consumer of that package is client-side.

package/build/consts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The agent service alias.
+ *
+ * Deliberately plural, and deliberately not `agent`: a consuming application very often already
+ * has a service of its own called that (the viable platform's Kubernetes-facing `AgentService` is
+ * registered under `agent`), and a context accessor collision is silent — the second registration
+ * simply wins and every later lookup resolves the wrong service.
+ */
+export declare const AGENTS_SERVICE = "agents";
+/**
+ * Port names.
+ *
+ * These are the keys a consumer binds its own storage under; the package never names a storage
+ * technology. A port left unbound is not an error — the plugin that needs it degrades to a no-op,
+ * the same way `ExecutionService.checkpoint` does with no plugin registered.
+ */
+export declare const AGENT_CONVERSATION_STORE = "agent-conversation-store";
+export declare const AGENT_RUN_STATE_STORE = "agent-run-state-store";
+export declare const AGENT_MEMORY_GRAPH_STORE = "agent-memory-graph-store";
+export declare const AGENT_MEMORY_EVENTS_STORE = "agent-memory-events-store";
+/** The lifecycle flow every agent run is driven through. */
+export declare const AGENT_RUN_FLOW = "agent-run";
+/**
+ * The steps of {@link AGENT_RUN_FLOW}.
+ *
+ * These are recoverable LIFECYCLE stages, not conversational turns. A ReAct loop's turn count is
+ * unbounded and its messages are not scalars, while `FlowPayload` holds flat scalars only — so the
+ * loop lives inside `Working` and only its counter travels in the payload. What the steps buy is
+ * the ability to say where a crashed run has to resume: at `Working` from the last checkpoint, or
+ * at `Finalizing` when the loop finished but the compaction never committed.
+ */
+export declare enum AgentRunStep {
+    Received = "received",
+    Prepared = "prepared",
+    Working = "working",
+    Finalizing = "finalizing",
+    Finished = "finished",
+    Failed = "failed"
+}
+/** The transitions of {@link AGENT_RUN_FLOW}. */
+export declare enum AgentRunTransition {
+    Prepare = "prepare",
+    Work = "work",
+    Finalize = "finalize",
+    Finish = "finish",
+    Fail = "fail",
+    Resume = "resume"
+}
+/** How a run ended. Written on the conversation event so a reader can weigh the advice. */
+export declare enum AgentRunStatus {
+    Ok = "ok",
+    Failed = "failed"
+}
+/**
+ * Default caps.
+ *
+ * Every one of them is enforced by truncation after the model answers, never by asking the model
+ * to obey a limit. A cap in a prompt is a request; a cap in code is a cap.
+ */
+export declare const DEFAULT_SUMMARY_CHARS = 1200;
+export declare const DEFAULT_ADVICE_CHARS = 400;
+export declare const DEFAULT_EVENT_WINDOW = 3;
+export declare const DEFAULT_MEMORY_NODE_CHARS = 2000;
+export declare const DEFAULT_MEMORY_EVENTS_LIMIT = 50;
+/** Separator between a dedication's kind and its target — `project:<id>`. */
+export declare const SCOPE_SEP = ":";
+//# 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;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AAEpE,4DAA4D;AAC5D,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC;;;;;;;;GAQG;AACH,oBAAY,YAAY;IACtB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,2FAA2F;AAC3F,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AACzC,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAC7C,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,6EAA6E;AAC7E,eAAO,MAAM,SAAS,MAAM,CAAA"}

package/build/consts.js

@@ -0,0 +1,70 @@
+/**
+ * The agent service alias.
+ *
+ * Deliberately plural, and deliberately not `agent`: a consuming application very often already
+ * has a service of its own called that (the viable platform's Kubernetes-facing `AgentService` is
+ * registered under `agent`), and a context accessor collision is silent — the second registration
+ * simply wins and every later lookup resolves the wrong service.
+ */
+export const AGENTS_SERVICE = 'agents';
+/**
+ * Port names.
+ *
+ * These are the keys a consumer binds its own storage under; the package never names a storage
+ * technology. A port left unbound is not an error — the plugin that needs it degrades to a no-op,
+ * the same way `ExecutionService.checkpoint` does with no plugin registered.
+ */
+export const AGENT_CONVERSATION_STORE = 'agent-conversation-store';
+export const AGENT_RUN_STATE_STORE = 'agent-run-state-store';
+export const AGENT_MEMORY_GRAPH_STORE = 'agent-memory-graph-store';
+export const AGENT_MEMORY_EVENTS_STORE = 'agent-memory-events-store';
+/** The lifecycle flow every agent run is driven through. */
+export const AGENT_RUN_FLOW = 'agent-run';
+/**
+ * The steps of {@link AGENT_RUN_FLOW}.
+ *
+ * These are recoverable LIFECYCLE stages, not conversational turns. A ReAct loop's turn count is
+ * unbounded and its messages are not scalars, while `FlowPayload` holds flat scalars only — so the
+ * loop lives inside `Working` and only its counter travels in the payload. What the steps buy is
+ * the ability to say where a crashed run has to resume: at `Working` from the last checkpoint, or
+ * at `Finalizing` when the loop finished but the compaction never committed.
+ */
+export var AgentRunStep;
+(function (AgentRunStep) {
+    AgentRunStep["Received"] = "received";
+    AgentRunStep["Prepared"] = "prepared";
+    AgentRunStep["Working"] = "working";
+    AgentRunStep["Finalizing"] = "finalizing";
+    AgentRunStep["Finished"] = "finished";
+    AgentRunStep["Failed"] = "failed";
+})(AgentRunStep || (AgentRunStep = {}));
+/** The transitions of {@link AGENT_RUN_FLOW}. */
+export var AgentRunTransition;
+(function (AgentRunTransition) {
+    AgentRunTransition["Prepare"] = "prepare";
+    AgentRunTransition["Work"] = "work";
+    AgentRunTransition["Finalize"] = "finalize";
+    AgentRunTransition["Finish"] = "finish";
+    AgentRunTransition["Fail"] = "fail";
+    AgentRunTransition["Resume"] = "resume";
+})(AgentRunTransition || (AgentRunTransition = {}));
+/** How a run ended. Written on the conversation event so a reader can weigh the advice. */
+export var AgentRunStatus;
+(function (AgentRunStatus) {
+    AgentRunStatus["Ok"] = "ok";
+    AgentRunStatus["Failed"] = "failed";
+})(AgentRunStatus || (AgentRunStatus = {}));
+/**
+ * Default caps.
+ *
+ * Every one of them is enforced by truncation after the model answers, never by asking the model
+ * to obey a limit. A cap in a prompt is a request; a cap in code is a cap.
+ */
+export const DEFAULT_SUMMARY_CHARS = 1200;
+export const DEFAULT_ADVICE_CHARS = 400;
+export const DEFAULT_EVENT_WINDOW = 3;
+export const DEFAULT_MEMORY_NODE_CHARS = 2000;
+export const DEFAULT_MEMORY_EVENTS_LIMIT = 50;
+/** Separator between a dedication's kind and its target — `project:<id>`. */
+export const SCOPE_SEP = ':';
+//# 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;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAA;AAClE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAA;AAClE,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAA2B,CAAA;AAEpE,4DAA4D;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,YAOX;AAPD,WAAY,YAAY;IACtB,qCAAqB,CAAA;IACrB,qCAAqB,CAAA;IACrB,mCAAmB,CAAA;IACnB,yCAAyB,CAAA;IACzB,qCAAqB,CAAA;IACrB,iCAAiB,CAAA;AACnB,CAAC,EAPW,YAAY,KAAZ,YAAY,QAOvB;AAED,iDAAiD;AACjD,MAAM,CAAN,IAAY,kBAOX;AAPD,WAAY,kBAAkB;IAC5B,yCAAmB,CAAA;IACnB,mCAAa,CAAA;IACb,2CAAqB,CAAA;IACrB,uCAAiB,CAAA;IACjB,mCAAa,CAAA;IACb,uCAAiB,CAAA;AACnB,CAAC,EAPW,kBAAkB,KAAlB,kBAAkB,QAO7B;AAED,2FAA2F;AAC3F,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,2BAAS,CAAA;IACT,mCAAiB,CAAA;AACnB,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAA;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAA;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAA;AACrC,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAA;AAC7C,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAA;AAE7C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,11 @@
+import { ResilientError } from '@owlmeans/error';
+export declare class AgentCommonError extends ResilientError {
+    static typeName: string;
+    constructor(message?: string);
+}
+/** A run was asked to advance along a transition its current step does not offer. */
+export declare class AgentRunStateError extends AgentCommonError {
+    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,gBAAiB,SAAQ,cAAc;IAClD,OAAuB,QAAQ,EAAE,MAAM,CAAoC;IAE3E,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED,qFAAqF;AACrF,qBAAa,kBAAmB,SAAQ,gBAAgB;IACtD,OAAuB,QAAQ,EAAE,MAAM,CAAyC;IAEhF,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF"}

package/build/errors.js

@@ -0,0 +1,18 @@
+import { ResilientError } from '@owlmeans/error';
+export class AgentCommonError extends ResilientError {
+    static typeName = `Agent${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(AgentCommonError.typeName, `agent:${message}`);
+    }
+}
+/** A run was asked to advance along a transition its current step does not offer. */
+export class AgentRunStateError extends AgentCommonError {
+    static typeName = `RunState${AgentCommonError.typeName}`;
+    constructor(message = 'error') {
+        super(`run-state:${message}`);
+        this.type = AgentRunStateError.typeName;
+    }
+}
+ResilientError.registerErrorClass(AgentCommonError);
+ResilientError.registerErrorClass(AgentRunStateError);
+//# 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,gBAAiB,SAAQ,cAAc;IAC3C,MAAM,CAAU,QAAQ,GAAW,QAAQ,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE3E,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC,CAAA;IACtD,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,OAAO,kBAAmB,SAAQ,gBAAgB;IAC/C,MAAM,CAAU,QAAQ,GAAW,WAAW,gBAAgB,CAAC,QAAQ,EAAE,CAAA;IAEhF,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,aAAa,OAAO,EAAE,CAAC,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA"}

package/build/flows.d.ts

@@ -0,0 +1,22 @@
+import type { ShallowFlow } from '@owlmeans/flow';
+/**
+ * The lifecycle of one agent run.
+ *
+ * Read it as "how far did this run get", not "what did it say". Everything conversational happens
+ * inside `Working`; the steps exist so that a run interrupted anywhere can be told where to pick
+ * up. `Fail` is reachable from every working step, and `Resume` re-enters `Working` from a
+ * checkpoint.
+ *
+ * `service` is left as the flow name on every step. A flow step normally binds to a service or an
+ * entrypoint, but an agent run is driven by whoever holds the model — there is no second party to
+ * hand control to, and inventing one would put a name in the serialized state that nothing
+ * resolves.
+ *
+ * Each working step keeps exactly ONE non-explicit outgoing transition, so `FlowModel.next()`
+ * always has an unambiguous answer: that is what lets a driver advance the run without knowing the
+ * vocabulary. `Fail` is marked explicit precisely so it never becomes that automatic answer.
+ */
+export declare const agentRunFlow: ShallowFlow;
+/** Every flow this package declares, for a provider to serve. */
+export declare const agentFlows: ShallowFlow[];
+//# sourceMappingURL=flows.d.ts.map

package/build/flows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../src/flows.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAGjD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,WA8F1B,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,UAAU,EAAE,WAAW,EAAmB,CAAA"}

package/build/flows.js

@@ -0,0 +1,110 @@
+import { AGENT_RUN_FLOW, AgentRunStep, AgentRunTransition } from './consts.js';
+/**
+ * The lifecycle of one agent run.
+ *
+ * Read it as "how far did this run get", not "what did it say". Everything conversational happens
+ * inside `Working`; the steps exist so that a run interrupted anywhere can be told where to pick
+ * up. `Fail` is reachable from every working step, and `Resume` re-enters `Working` from a
+ * checkpoint.
+ *
+ * `service` is left as the flow name on every step. A flow step normally binds to a service or an
+ * entrypoint, but an agent run is driven by whoever holds the model — there is no second party to
+ * hand control to, and inventing one would put a name in the serialized state that nothing
+ * resolves.
+ *
+ * Each working step keeps exactly ONE non-explicit outgoing transition, so `FlowModel.next()`
+ * always has an unambiguous answer: that is what lets a driver advance the run without knowing the
+ * vocabulary. `Fail` is marked explicit precisely so it never becomes that automatic answer.
+ */
+export const agentRunFlow = {
+    flow: AGENT_RUN_FLOW,
+    initialStep: AgentRunStep.Received,
+    steps: {
+        [AgentRunStep.Received]: {
+            index: 0,
+            step: AgentRunStep.Received,
+            service: AGENT_RUN_FLOW,
+            initial: true,
+            transitions: {
+                [AgentRunTransition.Prepare]: {
+                    transition: AgentRunTransition.Prepare,
+                    step: AgentRunStep.Prepared,
+                },
+                [AgentRunTransition.Fail]: {
+                    transition: AgentRunTransition.Fail,
+                    step: AgentRunStep.Failed,
+                    explicit: true,
+                },
+            },
+        },
+        [AgentRunStep.Prepared]: {
+            index: 1,
+            step: AgentRunStep.Prepared,
+            service: AGENT_RUN_FLOW,
+            transitions: {
+                [AgentRunTransition.Work]: {
+                    transition: AgentRunTransition.Work,
+                    step: AgentRunStep.Working,
+                },
+                [AgentRunTransition.Fail]: {
+                    transition: AgentRunTransition.Fail,
+                    step: AgentRunStep.Failed,
+                    explicit: true,
+                },
+            },
+        },
+        [AgentRunStep.Working]: {
+            index: 2,
+            step: AgentRunStep.Working,
+            service: AGENT_RUN_FLOW,
+            transitions: {
+                [AgentRunTransition.Finalize]: {
+                    transition: AgentRunTransition.Finalize,
+                    step: AgentRunStep.Finalizing,
+                },
+                [AgentRunTransition.Fail]: {
+                    transition: AgentRunTransition.Fail,
+                    step: AgentRunStep.Failed,
+                    explicit: true,
+                },
+            },
+        },
+        [AgentRunStep.Finalizing]: {
+            index: 3,
+            step: AgentRunStep.Finalizing,
+            service: AGENT_RUN_FLOW,
+            transitions: {
+                [AgentRunTransition.Finish]: {
+                    transition: AgentRunTransition.Finish,
+                    step: AgentRunStep.Finished,
+                },
+                [AgentRunTransition.Fail]: {
+                    transition: AgentRunTransition.Fail,
+                    step: AgentRunStep.Failed,
+                    explicit: true,
+                },
+            },
+        },
+        [AgentRunStep.Finished]: {
+            index: 4,
+            step: AgentRunStep.Finished,
+            service: AGENT_RUN_FLOW,
+            transitions: {},
+        },
+        [AgentRunStep.Failed]: {
+            index: 5,
+            step: AgentRunStep.Failed,
+            service: AGENT_RUN_FLOW,
+            transitions: {
+                [AgentRunTransition.Resume]: {
+                    transition: AgentRunTransition.Resume,
+                    step: AgentRunStep.Working,
+                    explicit: true,
+                },
+            },
+        },
+    },
+};
+/** Every flow this package declares, for a provider to serve. */
+export const agentFlows = [agentRunFlow];
+//# sourceMappingURL=flows.js.map

package/build/flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.js","sourceRoot":"","sources":["../src/flows.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgB;IACvC,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,YAAY,CAAC,QAAQ;IAElC,KAAK,EAAE;QACL,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE;YACvB,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,YAAY,CAAC,QAAQ;YAC3B,OAAO,EAAE,cAAc;YACvB,OAAO,EAAE,IAAI;YACb,WAAW,EAAE;gBACX,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE;oBAC5B,UAAU,EAAE,kBAAkB,CAAC,OAAO;oBACtC,IAAI,EAAE,YAAY,CAAC,QAAQ;iBAC5B;gBACD,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE;oBACzB,UAAU,EAAE,kBAAkB,CAAC,IAAI;oBACnC,IAAI,EAAE,YAAY,CAAC,MAAM;oBACzB,QAAQ,EAAE,IAAI;iBACf;aACF;SACF;QAED,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE;YACvB,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,YAAY,CAAC,QAAQ;YAC3B,OAAO,EAAE,cAAc;YACvB,WAAW,EAAE;gBACX,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE;oBACzB,UAAU,EAAE,kBAAkB,CAAC,IAAI;oBACnC,IAAI,EAAE,YAAY,CAAC,OAAO;iBAC3B;gBACD,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE;oBACzB,UAAU,EAAE,kBAAkB,CAAC,IAAI;oBACnC,IAAI,EAAE,YAAY,CAAC,MAAM;oBACzB,QAAQ,EAAE,IAAI;iBACf;aACF;SACF;QAED,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE;YACtB,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,YAAY,CAAC,OAAO;YAC1B,OAAO,EAAE,cAAc;YACvB,WAAW,EAAE;gBACX,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE;oBAC7B,UAAU,EAAE,kBAAkB,CAAC,QAAQ;oBACvC,IAAI,EAAE,YAAY,CAAC,UAAU;iBAC9B;gBACD,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE;oBACzB,UAAU,EAAE,kBAAkB,CAAC,IAAI;oBACnC,IAAI,EAAE,YAAY,CAAC,MAAM;oBACzB,QAAQ,EAAE,IAAI;iBACf;aACF;SACF;QAED,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE;YACzB,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,YAAY,CAAC,UAAU;YAC7B,OAAO,EAAE,cAAc;YACvB,WAAW,EAAE;gBACX,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE;oBAC3B,UAAU,EAAE,kBAAkB,CAAC,MAAM;oBACrC,IAAI,EAAE,YAAY,CAAC,QAAQ;iBAC5B;gBACD,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE;oBACzB,UAAU,EAAE,kBAAkB,CAAC,IAAI;oBACnC,IAAI,EAAE,YAAY,CAAC,MAAM;oBACzB,QAAQ,EAAE,IAAI;iBACf;aACF;SACF;QAED,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE;YACvB,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,YAAY,CAAC,QAAQ;YAC3B,OAAO,EAAE,cAAc;YACvB,WAAW,EAAE,EAAE;SAChB;QAED,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE;YACrB,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,YAAY,CAAC,MAAM;YACzB,OAAO,EAAE,cAAc;YACvB,WAAW,EAAE;gBACX,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE;oBAC3B,UAAU,EAAE,kBAAkB,CAAC,MAAM;oBACrC,IAAI,EAAE,YAAY,CAAC,OAAO;oBAC1B,QAAQ,EAAE,IAAI;iBACf;aACF;SACF;KACF;CACF,CAAA;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,UAAU,GAAkB,CAAC,YAAY,CAAC,CAAA"}

package/build/helpers/conversation.d.ts

@@ -0,0 +1,26 @@
+import type { LlmPurpose } from '@owlmeans/llm-common';
+import type { ConversationRef } from '../types.js';
+/**
+ * The conversation a run belongs to.
+ *
+ * An LLM purpose already carries the only correlation key most applications have — `dedication`,
+ * conventionally `<kind>:<id>`. Deriving the conversation from it means an application gets
+ * continuity without inventing and threading a second identifier, and two runs dedicated to the
+ * same subject land in the same conversation by construction.
+ *
+ * The scope is the dedication's TARGET rather than the whole string, so conversations addressed at
+ * different granularities (a project, one of its stories) still share the subject their memory is
+ * filed under. Both halves can be overridden for an application whose threads are not one per
+ * dedication.
+ */
+export declare const conversationFor: (purpose: LlmPurpose | undefined, override?: Partial<ConversationRef>) => ConversationRef;
+/**
+ * Cut `text` to `max` characters on a boundary a reader will not trip over.
+ *
+ * Every cap in this package lands here, because a model asked for "at most N characters" answers
+ * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
+ * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
+ * sentence, then word break inside the last quarter of the budget, and always marks itself.
+ */
+export declare const truncateAt: (text: string, max: number) => string;
+//# sourceMappingURL=conversation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/helpers/conversation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,YACjB,UAAU,GAAG,SAAS,aACpB,OAAO,CAAC,eAAe,CAAC,KAClC,eASF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,OAAO,MAAM,KAAG,MAsBtD,CAAA"}

package/build/helpers/conversation.js

@@ -0,0 +1,52 @@
+import { SCOPE_SEP } from '../consts.js';
+/**
+ * The conversation a run belongs to.
+ *
+ * An LLM purpose already carries the only correlation key most applications have — `dedication`,
+ * conventionally `<kind>:<id>`. Deriving the conversation from it means an application gets
+ * continuity without inventing and threading a second identifier, and two runs dedicated to the
+ * same subject land in the same conversation by construction.
+ *
+ * The scope is the dedication's TARGET rather than the whole string, so conversations addressed at
+ * different granularities (a project, one of its stories) still share the subject their memory is
+ * filed under. Both halves can be overridden for an application whose threads are not one per
+ * dedication.
+ */
+export const conversationFor = (purpose, override) => {
+    const dedication = purpose?.dedication ?? '';
+    const separator = dedication.indexOf(SCOPE_SEP);
+    const target = separator < 0 ? dedication : dedication.slice(separator + 1);
+    return {
+        conversationId: override?.conversationId ?? (dedication !== '' ? dedication : 'anonymous'),
+        scope: override?.scope ?? (target !== '' ? target : 'anonymous'),
+    };
+};
+/**
+ * Cut `text` to `max` characters on a boundary a reader will not trip over.
+ *
+ * Every cap in this package lands here, because a model asked for "at most N characters" answers
+ * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
+ * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
+ * sentence, then word break inside the last quarter of the budget, and always marks itself.
+ */
+export const truncateAt = (text, max) => {
+    const trimmed = text.trim();
+    if (trimmed.length <= max) {
+        return trimmed;
+    }
+    if (max <= 1) {
+        return trimmed.slice(0, Math.max(0, max));
+    }
+    const ellipsis = '…';
+    const budget = max - ellipsis.length;
+    const head = trimmed.slice(0, budget);
+    const floor = Math.floor(budget * 0.75);
+    for (const boundary of ['\n\n', '\n', '. ', ' ']) {
+        const at = head.lastIndexOf(boundary);
+        if (at >= floor) {
+            return head.slice(0, boundary === '. ' ? at + 1 : at).trimEnd() + ellipsis;
+        }
+    }
+    return head.trimEnd() + ellipsis;
+};
+//# sourceMappingURL=conversation.js.map

package/build/helpers/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/helpers/conversation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAA+B,EAC/B,QAAmC,EAClB,EAAE;IACnB,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAA;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAA;IAE3E,OAAO;QACL,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAC1F,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;KACjE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAA;IACpB,MAAM,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEvC,KAAK,MAAM,QAAQ,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;QACrC,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAA;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAA;AAClC,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export * from './consts.js';
+export * from './errors.js';
+export type * from './types.js';
+export * from './flows.js';
+export * from './helpers/conversation.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

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

package/build/index.js

@@ -0,0 +1,5 @@
+export * from './consts.js';
+export * from './errors.js';
+export * from './flows.js';
+export * from './helpers/conversation.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,cAAc,YAAY,CAAA;AAC1B,cAAc,2BAA2B,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,97 @@
+import type { ResourceRecord } from '@owlmeans/resource';
+import type { ExecutionState } from '@owlmeans/llm-common';
+import type { AgentRunStatus } from './consts.js';
+/**
+ * What a conversation is, as an address.
+ *
+ * `conversationId` is the thread a run belongs to; `scope` is the wider subject the thread is
+ * about — for a project-dedicated agent the two coincide, but memory is scoped per project while
+ * conversations may be finer-grained, so they are separate fields rather than one.
+ */
+export interface ConversationRef {
+    conversationId: string;
+    scope: string;
+}
+/**
+ * One finished run, compacted.
+ *
+ * Two parts on purpose: `summary` says what happened, `advice` says what to do next. The second is
+ * what an agent actually needs on the way in — a summary alone leaves the next run to re-derive
+ * the plan from the outcome, which is where it invents a different one.
+ *
+ * Timestamps are ISO strings, never `Date`: these contracts cross process boundaries and storage
+ * backends, and must survive `JSON.stringify` unchanged. A consumer whose store prefers dates maps
+ * them at its own adapter boundary.
+ */
+export interface ConversationEvent extends ResourceRecord {
+    conversationId: string;
+    scope: string;
+    /** Monotonic within a conversation, allocated by the store. */
+    seq: number;
+    createdAt: string;
+    /** The ask that opened the run, truncated. Present so a reader can see what was attempted. */
+    prompt?: string;
+    summary: string;
+    advice?: string;
+    status: AgentRunStatus;
+}
+/** What a store is asked to append; `seq` and `id` are the store's to allocate. */
+export interface ConversationEventInput extends Omit<ConversationEvent, 'id' | 'seq' | 'createdAt'> {
+    createdAt?: string;
+}
+/**
+ * The data plane of a run.
+ *
+ * `flow` is the serialized {@link import('@owlmeans/flow').FlowModel} state — the control plane
+ * collapsed to a string — and `state` is the execution snapshot the LLM layer produces. Keeping
+ * them in one record is what makes a resume a single read.
+ */
+export interface AgentRunState extends ResourceRecord {
+    id: string;
+    conversationId: string;
+    flow: string;
+    state: ExecutionState;
+    updatedAt: string;
+}
+/**
+ * A node of the subsystem memory graph.
+ *
+ * `subsystem` is the lookup key within a scope, and `links` are the other subsystems this one
+ * refers to. The graph is deliberately shallow: agents read a node and follow a link or two, they
+ * do not traverse.
+ */
+export interface MemoryNode extends ResourceRecord {
+    scope: string;
+    subsystem: string;
+    content: string;
+    links: string[];
+    updatedAt: string;
+}
+/** An entry in the bounded event-sequence memory. */
+export interface MemoryEvent extends ResourceRecord {
+    scope: string;
+    /** Monotonic within a scope, allocated by the store. */
+    seq: number;
+    kind: string;
+    content: string;
+    createdAt: string;
+}
+/** What a store is asked to append; `seq` and `id` are the store's to allocate. */
+export interface MemoryEventInput extends Omit<MemoryEvent, 'id' | 'seq' | 'createdAt'> {
+    createdAt?: string;
+}
+/**
+ * What a transport carries.
+ *
+ * The execution state travels by REFERENCE (`stateRef`), not by value: a project execution's state
+ * holds the whole project specification, and a queue whose messages carry that is a queue that
+ * falls over on the first large project. The flow string is small enough to inline, and it is what
+ * a consumer needs to route the message before it reads anything.
+ */
+export interface AgentRunMessage {
+    id: string;
+    conversationId: string;
+    flow: string;
+    stateRef?: string;
+}
+//# 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":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,cAAc,CAAA;CACvB;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;IACjG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,cAAc,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;IACrF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB"}

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,40 @@
+{
+  "name": "@owlmeans/agent-common",
+  "version": "0.1.18-rc.7",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 174 && 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"
+    }
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@owlmeans/error": "^0.1.18-rc.6",
+    "@owlmeans/flow": "^0.1.18-rc.6",
+    "@owlmeans/llm-common": "^0.1.18-rc.6",
+    "@owlmeans/resource": "^0.1.18-rc.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,73 @@
+/**
+ * The agent service alias.
+ *
+ * Deliberately plural, and deliberately not `agent`: a consuming application very often already
+ * has a service of its own called that (the viable platform's Kubernetes-facing `AgentService` is
+ * registered under `agent`), and a context accessor collision is silent — the second registration
+ * simply wins and every later lookup resolves the wrong service.
+ */
+export const AGENTS_SERVICE = 'agents'
+
+/**
+ * Port names.
+ *
+ * These are the keys a consumer binds its own storage under; the package never names a storage
+ * technology. A port left unbound is not an error — the plugin that needs it degrades to a no-op,
+ * the same way `ExecutionService.checkpoint` does with no plugin registered.
+ */
+export const AGENT_CONVERSATION_STORE = 'agent-conversation-store'
+export const AGENT_RUN_STATE_STORE = 'agent-run-state-store'
+export const AGENT_MEMORY_GRAPH_STORE = 'agent-memory-graph-store'
+export const AGENT_MEMORY_EVENTS_STORE = 'agent-memory-events-store'
+
+/** The lifecycle flow every agent run is driven through. */
+export const AGENT_RUN_FLOW = 'agent-run'
+
+/**
+ * The steps of {@link AGENT_RUN_FLOW}.
+ *
+ * These are recoverable LIFECYCLE stages, not conversational turns. A ReAct loop's turn count is
+ * unbounded and its messages are not scalars, while `FlowPayload` holds flat scalars only — so the
+ * loop lives inside `Working` and only its counter travels in the payload. What the steps buy is
+ * the ability to say where a crashed run has to resume: at `Working` from the last checkpoint, or
+ * at `Finalizing` when the loop finished but the compaction never committed.
+ */
+export enum AgentRunStep {
+  Received = 'received',
+  Prepared = 'prepared',
+  Working = 'working',
+  Finalizing = 'finalizing',
+  Finished = 'finished',
+  Failed = 'failed',
+}
+
+/** The transitions of {@link AGENT_RUN_FLOW}. */
+export enum AgentRunTransition {
+  Prepare = 'prepare',
+  Work = 'work',
+  Finalize = 'finalize',
+  Finish = 'finish',
+  Fail = 'fail',
+  Resume = 'resume',
+}
+
+/** How a run ended. Written on the conversation event so a reader can weigh the advice. */
+export enum AgentRunStatus {
+  Ok = 'ok',
+  Failed = 'failed',
+}
+
+/**
+ * Default caps.
+ *
+ * Every one of them is enforced by truncation after the model answers, never by asking the model
+ * to obey a limit. A cap in a prompt is a request; a cap in code is a cap.
+ */
+export const DEFAULT_SUMMARY_CHARS = 1200
+export const DEFAULT_ADVICE_CHARS = 400
+export const DEFAULT_EVENT_WINDOW = 3
+export const DEFAULT_MEMORY_NODE_CHARS = 2000
+export const DEFAULT_MEMORY_EVENTS_LIMIT = 50
+
+/** Separator between a dedication's kind and its target — `project:<id>`. */
+export const SCOPE_SEP = ':'

package/src/errors.ts

@@ -0,0 +1,22 @@
+import { ResilientError } from '@owlmeans/error'
+
+export class AgentCommonError extends ResilientError {
+  public static override typeName: string = `Agent${ResilientError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(AgentCommonError.typeName, `agent:${message}`)
+  }
+}
+
+/** A run was asked to advance along a transition its current step does not offer. */
+export class AgentRunStateError extends AgentCommonError {
+  public static override typeName: string = `RunState${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`run-state:${message}`)
+    this.type = AgentRunStateError.typeName
+  }
+}
+
+ResilientError.registerErrorClass(AgentCommonError)
+ResilientError.registerErrorClass(AgentRunStateError)

package/src/flows.ts

@@ -0,0 +1,118 @@
+import type { ShallowFlow } from '@owlmeans/flow'
+import { AGENT_RUN_FLOW, AgentRunStep, AgentRunTransition } from './consts.js'
+
+/**
+ * The lifecycle of one agent run.
+ *
+ * Read it as "how far did this run get", not "what did it say". Everything conversational happens
+ * inside `Working`; the steps exist so that a run interrupted anywhere can be told where to pick
+ * up. `Fail` is reachable from every working step, and `Resume` re-enters `Working` from a
+ * checkpoint.
+ *
+ * `service` is left as the flow name on every step. A flow step normally binds to a service or an
+ * entrypoint, but an agent run is driven by whoever holds the model — there is no second party to
+ * hand control to, and inventing one would put a name in the serialized state that nothing
+ * resolves.
+ *
+ * Each working step keeps exactly ONE non-explicit outgoing transition, so `FlowModel.next()`
+ * always has an unambiguous answer: that is what lets a driver advance the run without knowing the
+ * vocabulary. `Fail` is marked explicit precisely so it never becomes that automatic answer.
+ */
+export const agentRunFlow: ShallowFlow = {
+  flow: AGENT_RUN_FLOW,
+  initialStep: AgentRunStep.Received,
+
+  steps: {
+    [AgentRunStep.Received]: {
+      index: 0,
+      step: AgentRunStep.Received,
+      service: AGENT_RUN_FLOW,
+      initial: true,
+      transitions: {
+        [AgentRunTransition.Prepare]: {
+          transition: AgentRunTransition.Prepare,
+          step: AgentRunStep.Prepared,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Prepared]: {
+      index: 1,
+      step: AgentRunStep.Prepared,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Work]: {
+          transition: AgentRunTransition.Work,
+          step: AgentRunStep.Working,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Working]: {
+      index: 2,
+      step: AgentRunStep.Working,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Finalize]: {
+          transition: AgentRunTransition.Finalize,
+          step: AgentRunStep.Finalizing,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Finalizing]: {
+      index: 3,
+      step: AgentRunStep.Finalizing,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Finish]: {
+          transition: AgentRunTransition.Finish,
+          step: AgentRunStep.Finished,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Finished]: {
+      index: 4,
+      step: AgentRunStep.Finished,
+      service: AGENT_RUN_FLOW,
+      transitions: {},
+    },
+
+    [AgentRunStep.Failed]: {
+      index: 5,
+      step: AgentRunStep.Failed,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Resume]: {
+          transition: AgentRunTransition.Resume,
+          step: AgentRunStep.Working,
+          explicit: true,
+        },
+      },
+    },
+  },
+}
+
+/** Every flow this package declares, for a provider to serve. */
+export const agentFlows: ShallowFlow[] = [agentRunFlow]

package/src/helpers/conversation.ts

@@ -0,0 +1,62 @@
+import type { LlmPurpose } from '@owlmeans/llm-common'
+import { SCOPE_SEP } from '../consts.js'
+import type { ConversationRef } from '../types.js'
+
+/**
+ * The conversation a run belongs to.
+ *
+ * An LLM purpose already carries the only correlation key most applications have — `dedication`,
+ * conventionally `<kind>:<id>`. Deriving the conversation from it means an application gets
+ * continuity without inventing and threading a second identifier, and two runs dedicated to the
+ * same subject land in the same conversation by construction.
+ *
+ * The scope is the dedication's TARGET rather than the whole string, so conversations addressed at
+ * different granularities (a project, one of its stories) still share the subject their memory is
+ * filed under. Both halves can be overridden for an application whose threads are not one per
+ * dedication.
+ */
+export const conversationFor = (
+  purpose: LlmPurpose | undefined,
+  override?: Partial<ConversationRef>,
+): ConversationRef => {
+  const dedication = purpose?.dedication ?? ''
+  const separator = dedication.indexOf(SCOPE_SEP)
+  const target = separator < 0 ? dedication : dedication.slice(separator + 1)
+
+  return {
+    conversationId: override?.conversationId ?? (dedication !== '' ? dedication : 'anonymous'),
+    scope: override?.scope ?? (target !== '' ? target : 'anonymous'),
+  }
+}
+
+/**
+ * Cut `text` to `max` characters on a boundary a reader will not trip over.
+ *
+ * Every cap in this package lands here, because a model asked for "at most N characters" answers
+ * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
+ * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
+ * sentence, then word break inside the last quarter of the budget, and always marks itself.
+ */
+export const truncateAt = (text: string, max: number): string => {
+  const trimmed = text.trim()
+  if (trimmed.length <= max) {
+    return trimmed
+  }
+  if (max <= 1) {
+    return trimmed.slice(0, Math.max(0, max))
+  }
+
+  const ellipsis = '…'
+  const budget = max - ellipsis.length
+  const head = trimmed.slice(0, budget)
+  const floor = Math.floor(budget * 0.75)
+
+  for (const boundary of ['\n\n', '\n', '. ', ' ']) {
+    const at = head.lastIndexOf(boundary)
+    if (at >= floor) {
+      return head.slice(0, boundary === '. ' ? at + 1 : at).trimEnd() + ellipsis
+    }
+  }
+
+  return head.trimEnd() + ellipsis
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './consts.js'
+export * from './errors.js'
+export type * from './types.js'
+export * from './flows.js'
+export * from './helpers/conversation.js'

package/src/types.ts

@@ -0,0 +1,104 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { ExecutionState } from '@owlmeans/llm-common'
+import type { AgentRunStatus } from './consts.js'
+
+/**
+ * What a conversation is, as an address.
+ *
+ * `conversationId` is the thread a run belongs to; `scope` is the wider subject the thread is
+ * about — for a project-dedicated agent the two coincide, but memory is scoped per project while
+ * conversations may be finer-grained, so they are separate fields rather than one.
+ */
+export interface ConversationRef {
+  conversationId: string
+  scope: string
+}
+
+/**
+ * One finished run, compacted.
+ *
+ * Two parts on purpose: `summary` says what happened, `advice` says what to do next. The second is
+ * what an agent actually needs on the way in — a summary alone leaves the next run to re-derive
+ * the plan from the outcome, which is where it invents a different one.
+ *
+ * Timestamps are ISO strings, never `Date`: these contracts cross process boundaries and storage
+ * backends, and must survive `JSON.stringify` unchanged. A consumer whose store prefers dates maps
+ * them at its own adapter boundary.
+ */
+export interface ConversationEvent extends ResourceRecord {
+  conversationId: string
+  scope: string
+  /** Monotonic within a conversation, allocated by the store. */
+  seq: number
+  createdAt: string
+  /** The ask that opened the run, truncated. Present so a reader can see what was attempted. */
+  prompt?: string
+  summary: string
+  advice?: string
+  status: AgentRunStatus
+}
+
+/** What a store is asked to append; `seq` and `id` are the store's to allocate. */
+export interface ConversationEventInput extends Omit<ConversationEvent, 'id' | 'seq' | 'createdAt'> {
+  createdAt?: string
+}
+
+/**
+ * The data plane of a run.
+ *
+ * `flow` is the serialized {@link import('@owlmeans/flow').FlowModel} state — the control plane
+ * collapsed to a string — and `state` is the execution snapshot the LLM layer produces. Keeping
+ * them in one record is what makes a resume a single read.
+ */
+export interface AgentRunState extends ResourceRecord {
+  id: string
+  conversationId: string
+  flow: string
+  state: ExecutionState
+  updatedAt: string
+}
+
+/**
+ * A node of the subsystem memory graph.
+ *
+ * `subsystem` is the lookup key within a scope, and `links` are the other subsystems this one
+ * refers to. The graph is deliberately shallow: agents read a node and follow a link or two, they
+ * do not traverse.
+ */
+export interface MemoryNode extends ResourceRecord {
+  scope: string
+  subsystem: string
+  content: string
+  links: string[]
+  updatedAt: string
+}
+
+/** An entry in the bounded event-sequence memory. */
+export interface MemoryEvent extends ResourceRecord {
+  scope: string
+  /** Monotonic within a scope, allocated by the store. */
+  seq: number
+  kind: string
+  content: string
+  createdAt: string
+}
+
+/** What a store is asked to append; `seq` and `id` are the store's to allocate. */
+export interface MemoryEventInput extends Omit<MemoryEvent, 'id' | 'seq' | 'createdAt'> {
+  createdAt?: string
+}
+
+/**
+ * What a transport carries.
+ *
+ * The execution state travels by REFERENCE (`stateRef`), not by value: a project execution's state
+ * holds the whole project specification, and a queue whose messages carry that is a queue that
+ * falls over on the first large project. The flow string is small enough to inline, and it is what
+ * a consumer needs to route the message before it reads anything.
+ */
+export interface AgentRunMessage {
+  id: string
+  conversationId: string
+  flow: string
+  stateRef?: string
+}

package/tests/flow.spec.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test'
+import { makeFlowModel } from '@owlmeans/flow'
+import type { Flow, FlowProvider } from '@owlmeans/flow'
+import {
+  AGENT_RUN_FLOW, AgentRunStep, AgentRunTransition, agentRunFlow, conversationFor, truncateAt,
+} from '../src/index.js'
+
+/**
+ * A run's flow has to survive leaving the process, or the steps buy nothing: the whole reason the
+ * lifecycle is a flow rather than a field is that a crashed run can be told where to resume. These
+ * pin that the serialized form round-trips, which is also the gate on `@owlmeans/flow` being
+ * usable server-side at all — it has no server consumer anywhere else in the monorepo.
+ */
+const provider: FlowProvider = async flow => {
+  if (flow !== AGENT_RUN_FLOW) {
+    throw new Error(`unknown flow ${flow}`)
+  }
+  return { ...agentRunFlow, config: {}, prefabs: {} } as Flow
+}
+
+describe('agent-common — the run lifecycle flow', () => {
+  test('starts at Received and advances through the working steps', async () => {
+    const model = await makeFlowModel(agentRunFlow)
+    expect(model.step().step).toBe(AgentRunStep.Received)
+
+    model.transit(AgentRunTransition.Prepare, true)
+    expect(model.step().step).toBe(AgentRunStep.Prepared)
+
+    model.transit(AgentRunTransition.Work, true)
+    expect(model.step().step).toBe(AgentRunStep.Working)
+  })
+
+  test('offers exactly one automatic transition per working step', async () => {
+    const model = await makeFlowModel(agentRunFlow)
+
+    for (const expected of [AgentRunTransition.Prepare, AgentRunTransition.Work, AgentRunTransition.Finalize]) {
+      // `next()` is what lets a driver advance without knowing the vocabulary; it only works while
+      // exactly one outgoing transition is non-explicit. `Fail` is explicit for that reason.
+      expect(model.next().transition).toBe(expected)
+      model.transit(expected, true)
+    }
+
+    expect(model.step().step).toBe(AgentRunStep.Finalizing)
+  })
+
+  test('round-trips a mid-run state through its serialized form', async () => {
+    const model = await makeFlowModel(agentRunFlow)
+    model.transit(AgentRunTransition.Prepare, true)
+    const token = model.transit(AgentRunTransition.Work, true)
+
+    const restored = await makeFlowModel(token, provider)
+
+    expect(restored.step().step).toBe(AgentRunStep.Working)
+    expect(restored.state().flow).toBe(AGENT_RUN_FLOW)
+    expect(restored.state().ok).toBe(true)
+  })
+
+  test('carries a failure and its message across serialization', async () => {
+    const model = await makeFlowModel(agentRunFlow)
+    model.transit(AgentRunTransition.Prepare, true)
+    const token = model.transit(AgentRunTransition.Fail, false, 'the model refused')
+
+    const restored = await makeFlowModel(token, provider)
+
+    expect(restored.step().step).toBe(AgentRunStep.Failed)
+    expect(restored.state().ok).toBe(false)
+    expect(restored.state().message).toBe('the model refused')
+  })
+})
+
+describe('agent-common — conversation identity', () => {
+  test('derives the thread from a dedication and the scope from its target', () => {
+    expect(conversationFor({ dedication: 'project:abc123' }))
+      .toEqual({ conversationId: 'project:abc123', scope: 'abc123' })
+  })
+
+  test('degrades to a named default rather than an empty key', () => {
+    // An empty conversation id would silently collapse every run of every subject into one thread.
+    expect(conversationFor(undefined)).toEqual({ conversationId: 'anonymous', scope: 'anonymous' })
+    expect(conversationFor({})).toEqual({ conversationId: 'anonymous', scope: 'anonymous' })
+  })
+
+  test('accepts an override for an application whose threads are not one per dedication', () => {
+    expect(conversationFor({ dedication: 'story:s1' }, { scope: 'p1' }))
+      .toEqual({ conversationId: 'story:s1', scope: 'p1' })
+  })
+})
+
+describe('agent-common — truncation', () => {
+  test('leaves text inside the budget untouched', () => {
+    expect(truncateAt('  short  ', 100)).toBe('short')
+  })
+
+  test('never exceeds the budget', () => {
+    const long = 'word '.repeat(500)
+    expect(truncateAt(long, 40).length).toBeLessThanOrEqual(40)
+  })
+
+  test('cuts on a word boundary instead of mid-word', () => {
+    const source = 'alpha beta gamma delta epsilon zeta'
+    const result = truncateAt(source, 20)
+
+    expect(result).toBe('alpha beta gamma…')
+    // What was kept is a whole number of the original's words: the character the cut landed on is
+    // the space that followed the last one it took.
+    expect(source.startsWith(result.slice(0, -1))).toBe(true)
+    expect(source.charAt(result.length - 1)).toBe(' ')
+  })
+
+  test('prefers a sentence end when one falls inside the budget tail', () => {
+    expect(truncateAt('The first sentence ends here. Then a second one runs on.', 37))
+      .toBe('The first sentence ends here.…')
+  })
+
+  test('falls back to a word break when the sentence end is too far back to keep', () => {
+    // The boundary search only accepts a cut inside the last quarter of the budget — an earlier
+    // sentence end would throw away most of what fits, which is worse than a clean word break.
+    expect(truncateAt('One sentence here. And a second one that overflows.', 30))
+      .toBe('One sentence here. And a…')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.server.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
+}