toolnexus 0.2.0 → 0.3.0

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/skill.js

@@ -7,6 +7,7 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
@@ -18,24 +19,31 @@ The skill name must match one of the skills listed in your system prompt.`;
  */
 export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions and workflows for specific tasks.\n" +
     "Use the skill tool to load a skill when a task matches its description.";
-/** Minimal YAML frontmatter parser — only flat `key: value` pairs are needed. */
+/**
+ * Parse YAML frontmatter (between the leading `---` fences) with a real YAML
+ * parser, so folded (`>`)/literal (`|`) block scalars, quoting, and multi-line
+ * values all resolve correctly. Scalar values are coerced to strings.
+ */
 function parseFrontmatter(text) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!match)
         return { data: {}, content: text };
     const data = {};
-    for (const line of match[1].split(/\r?\n/)) {
-        const idx = line.indexOf(":");
-        if (idx === -1)
-            continue;
-        const key = line.slice(0, idx).trim();
-        let value = line.slice(idx + 1).trim();
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
+    let parsed;
+    try {
+        parsed = parseYaml(match[1]);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed && typeof parsed === "object") {
+        for (const [key, value] of Object.entries(parsed)) {
+            // Trim so block-scalar trailing newlines (chomping differs subtly between
+            // YAML libs) don't leak — keeps the five ports byte-identical.
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                data[key] = String(value).trim();
+            }
         }
-        if (key)
-            data[key] = value;
     }
     return { data, content: match[2] };
 }

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.0",
+  "version": "0.3.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,22 +11,40 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
-  "keywords": ["mcp", "llm", "agent", "skills", "tools", "openai", "anthropic", "gemini"],
+  "keywords": [
+    "mcp",
+    "llm",
+    "agent",
+    "skills",
+    "tools",
+    "openai",
+    "anthropic",
+    "gemini"
+  ],
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/muthuishere/toolnexus.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muthuishere/toolnexus.git"
+  },
   "homepage": "https://github.com/muthuishere/toolnexus#readme",
-  "bugs": { "url": "https://github.com/muthuishere/toolnexus/issues" },
+  "bugs": {
+    "url": "https://github.com/muthuishere/toolnexus/issues"
+  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0"
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "typescript": "^5.6.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
   }
 }

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/skill.ts

@@ -7,6 +7,7 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs"
 import path from "node:path"
 import { pathToFileURL } from "node:url"
+import { parse as parseYaml } from "yaml"
 import type { Tool, ToolResult } from "./types.js"
 
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
@@ -30,23 +31,29 @@ export interface SkillInfo {
   content: string // body after frontmatter
 }
 
-/** Minimal YAML frontmatter parser — only flat `key: value` pairs are needed. */
+/**
+ * Parse YAML frontmatter (between the leading `---` fences) with a real YAML
+ * parser, so folded (`>`)/literal (`|`) block scalars, quoting, and multi-line
+ * values all resolve correctly. Scalar values are coerced to strings.
+ */
 function parseFrontmatter(text: string): { data: Record<string, string>; content: string } {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
   if (!match) return { data: {}, content: text }
   const data: Record<string, string> = {}
-  for (const line of match[1].split(/\r?\n/)) {
-    const idx = line.indexOf(":")
-    if (idx === -1) continue
-    const key = line.slice(0, idx).trim()
-    let value = line.slice(idx + 1).trim()
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1)
+  let parsed: unknown
+  try {
+    parsed = parseYaml(match[1])
+  } catch {
+    parsed = null
+  }
+  if (parsed && typeof parsed === "object") {
+    for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+      // Trim so block-scalar trailing newlines (chomping differs subtly between
+      // YAML libs) don't leak — keeps the five ports byte-identical.
+      if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        data[key] = String(value).trim()
+      }
     }
-    if (key) data[key] = value
   }
   return { data, content: match[2] }
 }

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,
     })
   }