toolnexus 0.2.1 → 0.3.1

package/README.md

@@ -7,9 +7,9 @@
 and you have a working agent — MCP servers, agent skills, your own functions, and HTTP endpoints
 unified as one tool set, driving any LLM.
 
-> **Right-sized.** Not a framework (no builders, advisors, runnables, config), not a toy that
-> falls over the moment you need streaming or a retry. Everything a real agent needs — the loop,
-> hooks, streaming, retries, memory — and nothing it doesn't.
+> **Right-sized.** Not a framework (no builders, advisors, runnables, config graphs), not a toy
+> that falls over the moment you need streaming or a retry. Everything a real agent needs — the
+> loop, hooks, streaming, retries, memory — and nothing it doesn't.
 
 The JS/TypeScript port of [toolnexus](https://github.com/muthuishere/toolnexus) — the same
 library, byte-identical, also in **Python, Go, Java, and C#**. Built on
@@ -21,30 +21,89 @@ library, byte-identical, also in **Python, Go, Java, and C#**. Built on
 npm install toolnexus
 ```
 
-## An agent in 3 steps
+## Quick start
+
+Built-in tools are on by default, so an empty toolkit can already act:
 
 ```ts
 import { createToolkit, createClient } from "toolnexus"
 
-// 1. tools from an mcp.json + a skills/ folder
-const tk = await createToolkit({ mcpConfig: "./mcp.json", skillsDir: "./skills" })
-
-// 2. point at any OpenAI- or Anthropic-style endpoint
+const tk = await createToolkit()                        // 10 built-in tools, on by default
 const agent = createClient({
-  baseUrl: "https://openrouter.ai/api/v1",
-  style: "openai",                  // or "anthropic"
+  baseUrl: "https://openrouter.ai/api/v1",              // any OpenAI- or Anthropic-style endpoint
+  style: "openai",                                      // or "anthropic"
   model: "openai/gpt-4o-mini",
 })
 
-// 3. run — skills are injected into the system prompt, tools are called for you, looped to an answer
-const { text } = await agent.run("Refund order 1234 for the customer.", { toolkit: tk })
+const { text } = await agent.run("What files are in this folder?", { toolkit: tk })
 console.log(text)
-await tk.close()
 ```
 
 `createClient` reads the key from `OPENROUTER_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`
-by default. The loop runs call → execute tools → feed back → repeat (up to `maxTurns`, default 10),
-with hooks, streaming (`agent.stream(...)`), retries/backoff, and conversation memory available.
+(or pass `apiKey`). The loop runs call → execute tools → feed back → repeat (up to `maxTurns`,
+default 10), with hooks, streaming (`agent.stream(...)`), retries/backoff, timeout, and
+conversation memory available.
+
+## With MCP + skills
+
+Point the toolkit at an `mcp.json` and a `skills/` folder — every MCP server tool and every
+`SKILL.md` becomes part of the same tool set. Skills are injected into the system prompt; a
+single `skill` tool loads each on demand (progressive disclosure).
+
+```ts
+const tk = await createToolkit({
+  mcpConfig: "./mcp.json",     // path or a config object; local stdio + remote streamable-HTTP
+  skillsDir: "./skills",       // a folder of <name>/SKILL.md (string or string[])
+})
+
+const { text } = await agent.run("Refund order 1234 for the customer.", { toolkit: tk })
+console.log(text)
+await tk.close()               // disconnect MCP servers
+```
+
+## Conversations / memory
+
+`run()` is stateless — each call starts fresh. To keep a thread's history, use `ask()` with an
+`id`, or a `conversation()` object.
+
+**`ask(prompt, { toolkit, id? })`** — with an `id`, the client's `ConversationStore` remembers
+the thread: it *loads* that id's transcript, *runs*, *saves* the updated transcript, and returns
+the answer. The next `ask` with the same `id` continues it. Without an `id` it's a stateless
+one-shot (identical to `run`).
+
+```ts
+const agent = createClient({
+  baseUrl: "https://openrouter.ai/api/v1",
+  style: "openai",
+  model: "openai/gpt-4o-mini",
+  // store defaults to InMemoryConversationStore (process lifetime).
+})
+
+await agent.ask("My name is Muthu.", { toolkit: tk, id: "user-42" })
+const { text } = await agent.ask("What's my name?", { toolkit: tk, id: "user-42" })
+console.log(text)   // → "Your name is Muthu."
+```
+
+**Persist across processes.** A `ConversationStore` is two methods — implement it for a file, DB,
+or Redis and pass it as `store`:
+
+```ts
+import type { ConversationStore } from "toolnexus"
+
+interface ConversationStore {
+  get(id: string): Promise<any[] | undefined>   // stored transcript for id, or undefined
+  save(id: string, messages: any[]): Promise<void>
+}
+
+const agent = createClient({ baseUrl, style: "openai", model, store: myFileStore })
+```
+
+The default is `InMemoryConversationStore` (also exported). For a quick in-process thread without
+ids, `agent.conversation({ toolkit })` returns an object whose `.send(prompt)` retains history
+automatically (`.messages`, `.reset()`).
+
+The same `store` powers inbound A2A: `toolkit.serve` keys each peer's turns by the A2A
+`contextId` through `client.ask`, so a remote agent's conversation is remembered too (see below).
 
 ## Add your own tools
 
@@ -52,64 +111,53 @@ with hooks, streaming (`agent.stream(...)`), retries/backoff, and conversation m
 import { defineTool, httpTool } from "toolnexus"
 
 tk.register(
-  // a plain function → a tool
+  // a plain function → a tool  (run returns a string or a full ToolResult)
   defineTool({
-    name: "add", description: "Add two numbers",
-    inputSchema: { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"] },
-    run: ({ a, b }) => `${(a as number) + (b as number)}`,
+    name: "add",
+    description: "Add two numbers",
+    inputSchema: {
+      type: "object",
+      properties: { a: { type: "number" }, b: { type: "number" } },
+      required: ["a", "b"],
+    },
+    run: (args) => `${(args.a as number) + (args.b as number)}`,
   }),
   // a REST endpoint → a tool
   httpTool({
-    name: "create_ticket", description: "Create a ticket", method: "POST",
+    name: "create_ticket",
+    description: "Create a ticket",
+    method: "POST",
     url: "https://api.example.com/tickets",
     headers: { Authorization: "Bearer ${API_TOKEN}" },   // ${ENV} expands from process.env, never logged
-    inputSchema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
+    inputSchema: {
+      type: "object",
+      properties: { title: { type: "string" } },
+      required: ["title"],
+    },
   }),
 )
 ```
 
-URL `{placeholders}` are filled from args; `query` args go to the querystring; the rest become
-the JSON body. Non-2xx → `{ isError: true, output: "HTTP <status>: <body>" }`.
-
-## Bring your own loop
-
-Don't want the host loop? Use the schema adapters and execute calls yourself:
-
-```ts
-const tools  = tk.toOpenAI()       // or tk.toAnthropic() / tk.toGemini()
-const system = tk.skillsPrompt()   // skills catalog for your system prompt (opens with a preamble telling the model to use the skill tool)
-// when the model returns a tool call { name, arguments }:
-const res = await tk.execute(name, args)   // -> { output, isError, metadata }
-```
-
-## The four sources
-
-| Source | How |
-|--------|-----|
-| **MCP servers** | an `mcp.json` (`mcpServers`/`servers`/`mcp`); local stdio + remote streamable-HTTP, `headers` for auth |
-| **Agent skills** | a folder of `<name>/SKILL.md`; a `skill` tool loads each on demand + a system-prompt catalog |
-| **Native tools** | `defineTool({...})` — a function becomes a tool |
-| **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
-
-All four appear as one uniform `Tool` in `tk.tools()`. Each is à la carte — use just `loadMcp(config)`
-or `loadSkills(dir)` if that's all you need.
+For `httpTool`: URL `{placeholders}` are filled from args; `query` arg names go to the
+querystring (all args on GET); the rest become the JSON body (`body: "json" | "form" | "raw"`).
+Non-2xx → `{ isError: true, output: "HTTP <status>: <body>" }`.
 
 ## Built-in tools
 
 A fifth source ships **10 built-in tools** — `bash`, `read`, `write`, `edit`, `grep`, `glob`,
-`webfetch`, `question`, `apply_patch`, `todowrite` (names + input schemas match
-opencode) — so an agent can act with zero wiring. They appear in the tool schema
+`webfetch`, `question`, `apply_patch`, `todowrite` (names + input schemas match opencode) — so an
+agent can act with zero wiring. They appear in the tool schema
 (`toOpenAI()`/`toAnthropic()`/`toGemini()`), like MCP tools — not the system prompt.
 
 **On by default.** One global toggle turns the whole source off, or a per-tool `tools` map
 disables individual builtins on the all-on baseline:
 
 ```ts
-const tk = await createToolkit({ mcpConfig: "./mcp.json", builtins: false })
+const tk = await createToolkit({ builtins: false })
 // also accepts { disabled: true } or { enabled: false }
 
 // per-tool: drop bash, keep the other nine (unknown names ignored; whole-source-off still wins)
-const tk2 = await createToolkit({ mcpConfig: "./mcp.json", builtins: { tools: { bash: false } } })
+const tk2 = await createToolkit({ builtins: { tools: { bash: false } } })
 ```
 
 `bash`/`write`/`edit`/`apply_patch` run commands and mutate the filesystem — the toggle is the
@@ -136,7 +184,7 @@ await tk.addAgent("https://writer.example.com/.well-known/agent-card.json")
 ```
 
 `agent({ card, headers?, timeout?, pollEvery? })` — `headers` support `${ENV}` expansion (never
-logged); `timeout` defaults to 300000ms, `pollEvery` to 1000ms. A config file can also carry an
+logged); `timeout` defaults to 300000ms, `pollEvery` to 1000ms. A config object can also carry an
 `agents` block (mirrors `mcpServers`). A failing agent is isolated — logged, contributes no tools,
 never fatal.
 
@@ -144,12 +192,8 @@ never fatal.
 built from your **SKILL.md skills** (never raw tools):
 
 ```ts
-import { createClient } from "toolnexus"
-
-const agent = createClient({ baseUrl: "https://openrouter.ai/api/v1", style: "openai", model: "openai/gpt-4o-mini" })
-
 const handle = await tk.serve("127.0.0.1:0", {
-  client: agent,
+  client: agent,                  // a createClient(...) instance fulfils each task
   a2a: {
     name: "research-agent",
     description: "Answers research questions.",
@@ -161,26 +205,61 @@ console.log(handle.url)   // GET /.well-known/agent-card.json ; POST / (SendMess
 await handle.stop()
 ```
 
-`serve(addr, { client, a2a?, onTask? })` fulfils each inbound `SendMessage` task via `client.run`.
-Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"`, or your own.
+`serve(addr, { client, a2a?, onTask? })` fulfils each inbound `SendMessage` task via the client.
+Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"`, or your own. And
+it **remembers**: a message's A2A `contextId` keys the conversation through `client.ask`, so a
+peer's turns in the same context carry history via the client's `ConversationStore`.
+
+## Bring your own loop
+
+Don't want the host loop? Use the schema adapters and execute calls yourself:
+
+```ts
+const tools  = tk.toOpenAI()       // or tk.toAnthropic() / tk.toGemini()
+const system = tk.skillsPrompt()   // skills catalog for your system prompt
+// when the model returns a tool call { name, arguments }:
+const res = await tk.execute(name, args)   // → { output, isError, metadata }
+```
+
+## The four sources
+
+| Source | How |
+|--------|-----|
+| **MCP servers** | an `mcp.json` (`mcpServers`/`servers`/`mcp`); local stdio + remote streamable-HTTP, `headers` for auth |
+| **Agent skills** | a folder of `<name>/SKILL.md`; a `skill` tool loads each on demand + a system-prompt catalog |
+| **Native tools** | `defineTool({...})` — a function becomes a tool |
+| **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
+
+All appear as one uniform `Tool` in `tk.tools()`. Built-ins are a fifth source; remote A2A agents
+a sixth.
 
 ## API
 
 | Member | Description |
 |--------|-------------|
-| `createToolkit(opts)` | async factory → `Toolkit` |
-| `createClient(opts)` | the unified host loop (`run` / `stream`) |
+| `createToolkit(opts)` | async factory → `Toolkit` (`mcpConfig`, `skillsDir`, `builtins`, `agents`, `extraTools`) |
+| `createClient(opts)` | the unified host loop (`baseUrl`, `style`, `model`, `store?`, `hooks?`, `maxTurns?`, `retries?`, `timeoutMs?`) |
+| `client.run(prompt, { toolkit, signal?, history? })` | stateless run → `RunResult` |
+| `client.ask(prompt, { toolkit, id?, signal? })` | stateful with `id` (loads → runs → saves via `store`); one-shot without `id` |
+| `client.conversation({ toolkit })` | in-process multi-turn object — `.send(prompt)`, `.messages`, `.reset()` |
+| `client.stream(prompt, { toolkit })` | async-iterate `StreamEvent`s (text deltas, tool calls/results, usage, done) |
+| `ConversationStore` | `get(id)` / `save(id, messages)` — implement for file/db; default `InMemoryConversationStore` |
 | `tk.tools()` / `tk.get(name)` | the uniform tools |
+| `tk.register(...tools)` | add native/http/custom tools at runtime |
 | `tk.execute(name, args, ctx?)` | run a tool → `ToolResult` |
 | `tk.skillsPrompt()` | system-prompt skill catalog |
 | `tk.mcpStatus()` | per-server connection status |
 | `tk.toOpenAI()` / `toAnthropic()` / `toGemini()` | provider tool schemas |
-| `tk.register(...tools)` | add native/http/custom tools |
+| `tk.serve(addr, { client, a2a?, onTask? })` | serve the toolkit as an A2A agent → `ServeHandle` |
+| `tk.addAgent(cardUrl \| Agent)` | fetch a remote agent's card and register its skills as tools |
 | `tk.close()` | disconnect MCP servers |
+| `defineTool` / `httpTool` / `agent` | build native / HTTP / A2A tools |
+| `InMemoryConversationStore` · `InMemoryTaskStore` / `FileTaskStore` | default stores (memory / A2A tasks) |
 
 ## More
 
-Full docs, the other four language ports, the shared behavior spec, and runnable examples:
-**https://github.com/muthuishere/toolnexus**
+Full docs, the other four language ports, and the shared cross-language behavior contract
+([`SPEC.md`](https://github.com/muthuishere/toolnexus/blob/main/SPEC.md)) — plus runnable
+`examples/`: **https://github.com/muthuishere/toolnexus**
 
 MIT licensed.

package/dist/a2a.d.ts

@@ -22,6 +22,8 @@ export interface A2ATaskStatus {
 }
 export interface A2ATask {
     id: string;
+    /** Groups a peer's turns into one conversation (A2A contextId). */
+    contextId?: string;
     status: A2ATaskStatus;
     artifacts?: A2AArtifact[];
     history?: A2AMessage[];

package/dist/client.d.ts

@@ -21,6 +21,25 @@ export interface ClientOptions {
     retryBaseMs?: number;
     /** Whole-run deadline in ms; aborts the run (and its in-flight request) when exceeded. */
     timeoutMs?: number;
+    /** Conversation provider for `ask(prompt, { id })`. Default: in-memory (process lifetime).
+     * Supply a file/db store to persist conversations across processes. */
+    store?: ConversationStore;
+}
+/**
+ * Where `ask()` conversations are remembered — two methods. Ship the in-memory
+ * default; implement this for a file/db/redis provider to persist across processes.
+ */
+export interface ConversationStore {
+    /** Return the stored transcript for `id`, or undefined if none. */
+    get(id: string): Promise<any[] | undefined>;
+    /** Persist the (updated) transcript for `id`. */
+    save(id: string, messages: any[]): Promise<void>;
+}
+/** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
+export declare class InMemoryConversationStore implements ConversationStore {
+    private readonly map;
+    get(id: string): Promise<any[] | undefined>;
+    save(id: string, messages: any[]): Promise<void>;
 }
 /**
  * Lifecycle hooks around the agent loop. Each may observe, and (where noted)
@@ -124,12 +143,25 @@ export type StreamEvent = {
 };
 export declare class Client {
     private readonly opts;
+    /** Conversation provider for `ask()` — from opts.store, else in-memory. */
+    private readonly store;
     constructor(opts: ClientOptions);
     run(prompt: string, ctx: {
         toolkit: Toolkit;
         signal?: AbortSignal;
         history?: any[];
     }): Promise<RunResult>;
+    /**
+     * Stateful ask. With an `id`, the client's `store` remembers the conversation:
+     * it loads that id's transcript, runs, saves the updated transcript, and returns
+     * the answer — so the next `ask` with the same `id` continues it. Without an
+     * `id` it is a stateless one-shot (identical to `run`).
+     */
+    ask(prompt: string, ctx: {
+        toolkit: Toolkit;
+        id?: string;
+        signal?: AbortSignal;
+    }): Promise<RunResult>;
     /** A stateful multi-turn conversation that retains history across sends. */
     conversation(ctx: {
         toolkit: Toolkit;

package/dist/client.js

@@ -1,3 +1,14 @@
+/** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
+export class InMemoryConversationStore {
+    map = new Map();
+    async get(id) {
+        const m = this.map.get(id);
+        return m ? [...m] : undefined;
+    }
+    async save(id, messages) {
+        this.map.set(id, [...messages]);
+    }
+}
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 function delay(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -33,14 +44,31 @@ function resolveKey(opts) {
 }
 export class Client {
     opts;
+    /** Conversation provider for `ask()` — from opts.store, else in-memory. */
+    store;
     constructor(opts) {
         this.opts = opts;
+        this.store = opts.store ?? new InMemoryConversationStore();
     }
     async run(prompt, ctx) {
         return this.opts.style === "anthropic"
             ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
             : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history);
     }
+    /**
+     * Stateful ask. With an `id`, the client's `store` remembers the conversation:
+     * it loads that id's transcript, runs, saves the updated transcript, and returns
+     * the answer — so the next `ask` with the same `id` continues it. Without an
+     * `id` it is a stateless one-shot (identical to `run`).
+     */
+    async ask(prompt, ctx) {
+        if (!ctx.id)
+            return this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal });
+        const history = (await this.store.get(ctx.id)) ?? [];
+        const result = await this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal, history });
+        await this.store.save(ctx.id, result.messages);
+        return result;
+    }
     /** A stateful multi-turn conversation that retains history across sends. */
     conversation(ctx) {
         return new Conversation(this, ctx.toolkit, ctx.signal);

package/dist/serve.d.ts

@@ -67,8 +67,9 @@ export interface StartServerOptions {
     a2a?: A2AConfig;
     /** The toolkit's skills, for the card. */
     skills: SkillInfo[];
-    /** Runs one served Task through the client loop. */
-    runTask: (text: string) => Promise<RunResult>;
+    /** Runs one served Task through the client loop. `contextId` (from the A2A
+     * message) keys the conversation so served turns are remembered via the store. */
+    runTask: (text: string, contextId?: string) => Promise<RunResult>;
     onTask?: OnTask;
 }
 /**

package/dist/serve.js

@@ -149,11 +149,12 @@ export async function startA2AServer(opts) {
                 }
                 if (rpc?.method === "SendMessage") {
                     const text = messageText(rpc.params);
+                    const contextId = typeof rpc.params?.message?.contextId === "string" ? rpc.params.message.contextId : undefined;
                     const id = randomUUID();
-                    const submitted = { id, status: { state: "submitted" } };
+                    const submitted = { id, contextId, status: { state: "submitted" } };
                     // Persist submitted, kick fulfilment async, return the id immediately.
                     store.save(submitted).then(() => {
-                        void fulfil(id, text, store, runTask, onTask);
+                        void fulfil(id, text, store, runTask, onTask, contextId);
                         rpcOk(rpc.id, submitted);
                     });
                     return;
@@ -189,13 +190,15 @@ export async function startA2AServer(opts) {
  * Background fulfilment: submitted → working → (completed | failed). Never
  * throws — a fulfilment error becomes a `failed` Task, keeping the server alive.
  */
-async function fulfil(id, text, store, runTask, onTask) {
+async function fulfil(id, text, store, runTask, onTask, contextId) {
     let task;
     let result;
     let state;
     try {
         await store.save({ id, status: { state: "working" } });
-        result = await runTask(text);
+        // contextId groups a peer's turns into one conversation — thread it so the
+        // client's ConversationStore remembers across tasks in the same context.
+        result = await runTask(text, contextId);
         const artifact = {
             artifactId: randomUUID(),
             parts: [{ kind: "text", text: result.text }],

package/dist/toolkit.d.ts

@@ -37,7 +37,9 @@ export declare class Toolkit {
      * Serve this toolkit as an agent over HTTP. When the `a2a` profile is present
      * (inline, or a top-level `a2a` config block the toolkit was built from), it
      * mounts the A2A Agent Card (`/.well-known/agent-card.json`, built from skills)
-     * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by `client.run`.
+     * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by the client.
+     * A message's A2A `contextId` keys the conversation via `client.ask`, so a
+     * peer's turns are remembered through the client's ConversationStore.
      * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
      */
     serve(addr: string, opts: {

package/dist/toolkit.js

@@ -92,7 +92,9 @@ export class Toolkit {
      * Serve this toolkit as an agent over HTTP. When the `a2a` profile is present
      * (inline, or a top-level `a2a` config block the toolkit was built from), it
      * mounts the A2A Agent Card (`/.well-known/agent-card.json`, built from skills)
-     * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by `client.run`.
+     * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by the client.
+     * A message's A2A `contextId` keys the conversation via `client.ask`, so a
+     * peer's turns are remembered through the client's ConversationStore.
      * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
      */
     serve(addr, opts) {
@@ -102,7 +104,9 @@ export class Toolkit {
             addr,
             a2a,
             skills,
-            runTask: (text) => opts.client.run(text, { toolkit: this }),
+            runTask: (text, contextId) => contextId
+                ? opts.client.ask(text, { toolkit: this, id: contextId })
+                : opts.client.run(text, { toolkit: this }),
             onTask: opts.onTask,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/a2a.ts

@@ -54,6 +54,8 @@ export interface A2ATaskStatus {
 
 export interface A2ATask {
   id: string
+  /** Groups a peer's turns into one conversation (A2A contextId). */
+  contextId?: string
   status: A2ATaskStatus
   artifacts?: A2AArtifact[]
   history?: A2AMessage[]

package/src/client.ts

@@ -23,6 +23,32 @@ export interface ClientOptions {
   retryBaseMs?: number
   /** Whole-run deadline in ms; aborts the run (and its in-flight request) when exceeded. */
   timeoutMs?: number
+  /** Conversation provider for `ask(prompt, { id })`. Default: in-memory (process lifetime).
+   * Supply a file/db store to persist conversations across processes. */
+  store?: ConversationStore
+}
+
+/**
+ * Where `ask()` conversations are remembered — two methods. Ship the in-memory
+ * default; implement this for a file/db/redis provider to persist across processes.
+ */
+export interface ConversationStore {
+  /** Return the stored transcript for `id`, or undefined if none. */
+  get(id: string): Promise<any[] | undefined>
+  /** Persist the (updated) transcript for `id`. */
+  save(id: string, messages: any[]): Promise<void>
+}
+
+/** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
+export class InMemoryConversationStore implements ConversationStore {
+  private readonly map = new Map<string, any[]>()
+  async get(id: string): Promise<any[] | undefined> {
+    const m = this.map.get(id)
+    return m ? [...m] : undefined
+  }
+  async save(id: string, messages: any[]): Promise<void> {
+    this.map.set(id, [...messages])
+  }
 }
 
 const RETRYABLE = new Set([429, 500, 502, 503, 504])
@@ -114,7 +140,11 @@ function resolveKey(opts: ClientOptions): string {
 }
 
 export class Client {
-  constructor(private readonly opts: ClientOptions) {}
+  /** Conversation provider for `ask()` — from opts.store, else in-memory. */
+  private readonly store: ConversationStore
+  constructor(private readonly opts: ClientOptions) {
+    this.store = opts.store ?? new InMemoryConversationStore()
+  }
 
   async run(prompt: string, ctx: { toolkit: Toolkit; signal?: AbortSignal; history?: any[] }): Promise<RunResult> {
     return this.opts.style === "anthropic"
@@ -122,6 +152,20 @@ export class Client {
       : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history)
   }
 
+  /**
+   * Stateful ask. With an `id`, the client's `store` remembers the conversation:
+   * it loads that id's transcript, runs, saves the updated transcript, and returns
+   * the answer — so the next `ask` with the same `id` continues it. Without an
+   * `id` it is a stateless one-shot (identical to `run`).
+   */
+  async ask(prompt: string, ctx: { toolkit: Toolkit; id?: string; signal?: AbortSignal }): Promise<RunResult> {
+    if (!ctx.id) return this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal })
+    const history = (await this.store.get(ctx.id)) ?? []
+    const result = await this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal, history })
+    await this.store.save(ctx.id, result.messages)
+    return result
+  }
+
   /** A stateful multi-turn conversation that retains history across sends. */
   conversation(ctx: { toolkit: Toolkit; signal?: AbortSignal }): Conversation {
     return new Conversation(this, ctx.toolkit, ctx.signal)

package/src/serve.ts

@@ -158,8 +158,9 @@ export interface StartServerOptions {
   a2a?: A2AConfig
   /** The toolkit's skills, for the card. */
   skills: SkillInfo[]
-  /** Runs one served Task through the client loop. */
-  runTask: (text: string) => Promise<RunResult>
+  /** Runs one served Task through the client loop. `contextId` (from the A2A
+   * message) keys the conversation so served turns are remembered via the store. */
+  runTask: (text: string, contextId?: string) => Promise<RunResult>
   onTask?: OnTask
 }
 
@@ -222,11 +223,12 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
         }
         if (rpc?.method === "SendMessage") {
           const text = messageText(rpc.params)
+          const contextId = typeof rpc.params?.message?.contextId === "string" ? rpc.params.message.contextId : undefined
           const id = randomUUID()
-          const submitted: A2ATask = { id, status: { state: "submitted" } }
+          const submitted: A2ATask = { id, contextId, status: { state: "submitted" } }
           // Persist submitted, kick fulfilment async, return the id immediately.
           store.save(submitted).then(() => {
-            void fulfil(id, text, store, runTask, onTask)
+            void fulfil(id, text, store, runTask, onTask, contextId)
             rpcOk(rpc.id, submitted)
           })
           return
@@ -269,15 +271,18 @@ async function fulfil(
   id: string,
   text: string,
   store: TaskStore,
-  runTask: (text: string) => Promise<RunResult>,
+  runTask: (text: string, contextId?: string) => Promise<RunResult>,
   onTask?: OnTask,
+  contextId?: string,
 ): Promise<void> {
   let task: A2ATask
   let result: RunResult | undefined
   let state: A2ATaskState
   try {
     await store.save({ id, status: { state: "working" } })
-    result = await runTask(text)
+    // contextId groups a peer's turns into one conversation — thread it so the
+    // client's ConversationStore remembers across tasks in the same context.
+    result = await runTask(text, contextId)
     const artifact: A2AArtifact = {
       artifactId: randomUUID(),
       parts: [{ kind: "text", text: result.text }],

package/src/toolkit.ts

@@ -124,7 +124,9 @@ export class Toolkit {
    * Serve this toolkit as an agent over HTTP. When the `a2a` profile is present
    * (inline, or a top-level `a2a` config block the toolkit was built from), it
    * mounts the A2A Agent Card (`/.well-known/agent-card.json`, built from skills)
-   * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by `client.run`.
+   * and a JSON-RPC endpoint (`SendMessage` + `GetTask`) fulfilled by the client.
+   * A message's A2A `contextId` keys the conversation via `client.ask`, so a
+   * peer's turns are remembered through the client's ConversationStore.
    * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
    */
   serve(addr: string, opts: { client: Client; a2a?: A2AConfig; onTask?: OnTask }): Promise<ServeHandle> {
@@ -134,7 +136,10 @@ export class Toolkit {
       addr,
       a2a,
       skills,
-      runTask: (text) => opts.client.run(text, { toolkit: this }),
+      runTask: (text, contextId) =>
+        contextId
+          ? opts.client.ask(text, { toolkit: this, id: contextId })
+          : opts.client.run(text, { toolkit: this }),
       onTask: opts.onTask,
     })
   }