agentproc 0.1.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "agentproc",
+  "version": "0.1.0",
+  "description": "AgentProc Protocol SDK for Node.js — connect any Agent CLI to a messaging platform",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "node --test src/index.test.js"
+  },
+  "keywords": ["agentproc", "agent", "bridge", "protocol", "cli", "ai"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jeffkit/agentproc.git"
+  },
+  "homepage": "https://jeffkit.github.io/agentproc/"
+}

package/src/index.d.ts

@@ -0,0 +1,83 @@
+// Type declarations for agentproc
+// Protocol version: 0.1 (see spec/protocol.md)
+
+declare module 'agentproc' {
+
+  export const PROTOCOL_VERSION: string;
+
+  /** A single attachment on the user message (draft, multi-attachment). */
+  export interface Attachment {
+    /** Kind of attachment: 'image' | 'file' | 'audio' | 'video'. */
+    type: string;
+    /** URL the bridge has made available for fetching. */
+    url: string;
+    /** Optional filename or display name. */
+    name?: string;
+  }
+
+  /** Input context passed to the agent handler. */
+  export interface AgentContext {
+    /** User message text (AGENT_MESSAGE). */
+    message: string;
+    /** Session ID from the previous turn. Empty = new session. */
+    sessionId: string;
+    /** Human-readable session name (AGENT_SESSION_NAME). */
+    sessionName: string;
+    /** Sender identifier (AGENT_FROM_USER). */
+    fromUser: string;
+    /** Whether the bridge expects streaming output. */
+    streaming: boolean;
+    /** Protocol version the bridge implements. */
+    protocolVersion: string;
+    /** Image attachment URL. Empty if no image. */
+    imageUrl: string;
+    /** File attachment URL. Empty if no file. */
+    fileUrl: string;
+    /** Parsed attachments from AGENT_ATTACHMENTS (draft). Empty array when unset. */
+    attachments: Attachment[];
+
+    /** Send a streaming chunk to the user immediately. */
+    sendPartial(text: string): void;
+    /** Send an error message to the user. Honored regardless of streaming mode. */
+    sendError(text: string): void;
+  }
+
+  /** Return value from the agent handler. */
+  export interface AgentResult {
+    /** Final reply text. */
+    response?: string;
+    /** Session ID to persist. */
+    sessionId?: string;
+  }
+
+  /** One entry in a session's conversation history. */
+  export interface HistoryEntry {
+    role: string;
+    content: string;
+    timestamp: string;
+  }
+
+  /** Run a handler as an AgentProc-compliant process. */
+  export function createProfile(
+    handler: (ctx: AgentContext) => Promise<AgentResult | string | void>
+  ): void;
+
+  /** Load conversation history for a session. Returns [] if sessionId is empty. */
+  export function loadHistory(sessionId: string, sessionDir?: string): HistoryEntry[];
+
+  /** Append entries to a session's JSONL history file. No-op if sessionId is empty. */
+  export function appendHistory(
+    sessionId: string,
+    entries: Array<{ role: string; content: string; ts?: string }>,
+    sessionDir?: string
+  ): void;
+
+  /** Resolve the JSONL history file path for a session. Throws if sessionId is empty. */
+  export function sessionFilePath(sessionId: string, sessionDir?: string): string;
+
+  /** Parse AGENT_ATTACHMENTS JSON. Returns [] on parse failure. */
+  export function parseAttachments(raw: string): Attachment[];
+
+  /** Reject with a user-readable error; surfaced via AGENT_ERROR. */
+  export function protocolError(message: string): Promise<never>;
+}

package/src/index.js

@@ -0,0 +1,223 @@
+'use strict';
+/**
+ * agentproc — AgentProc Protocol SDK (Node.js)
+ *
+ * Implements the AgentProc P0 protocol (spec/protocol.md, v0.1.0).
+ *
+ * Protocol contract:
+ *   Input  — env vars: AGENT_MESSAGE, AGENT_SESSION_ID, AGENT_SESSION_NAME,
+ *                      AGENT_FROM_USER, AGENT_STREAMING, AGENT_PROTOCOL_VERSION,
+ *                      AGENT_IMAGE_URL, AGENT_FILE_URL, AGENT_ATTACHMENTS (draft)
+ *   Output — stdout (sentinel-prefixed lines):
+ *              AGENT_SESSION:<opaque-id>     — declare session id (last wins)
+ *              AGENT_PARTIAL:<json-string>   — streaming chunk
+ *              AGENT_ERROR:<json-string>     — error message to forward to user
+ *              everything else               = final reply body
+ *   Exit   — 0 success, 1 error, 124 timeout, 130 SIGINT, 143 SIGTERM
+ *
+ * @example
+ * const { createProfile } = require('agentproc');
+ *
+ * createProfile(async ({ message, sessionId }) => {
+ *   const reply = await myAI(message);
+ *   return { response: reply, sessionId: newSessionId };
+ * });
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const PROTOCOL_VERSION = '0.1';
+
+// ---------------------------------------------------------------------------
+// History helpers (optional — for handlers calling LLM APIs directly)
+// ---------------------------------------------------------------------------
+
+function defaultSessionDir() {
+  return path.join(os.homedir(), '.agentproc', 'sessions');
+}
+
+/**
+ * Resolve the JSONL history file path for a session.
+ * @param {string} sessionId
+ * @param {string} [sessionDir]
+ * @returns {string}
+ * @throws {Error} when sessionId is empty
+ */
+function sessionFilePath(sessionId, sessionDir) {
+  if (!sessionId) {
+    throw new Error('sessionId must be non-empty');
+  }
+  return path.join(sessionDir || defaultSessionDir(), `${sessionId}.jsonl`);
+}
+
+/**
+ * Load conversation history for a session from its JSONL file.
+ * Returns [] if sessionId is empty or the file does not exist.
+ *
+ * @param {string} sessionId
+ * @param {string} [sessionDir]
+ * @returns {HistoryEntry[]}
+ */
+function loadHistory(sessionId, sessionDir) {
+  if (!sessionId) return [];
+  let file;
+  try {
+    file = sessionFilePath(sessionId, sessionDir);
+  } catch {
+    return [];
+  }
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean)
+    .map(d => ({
+      role: String(d.role || ''),
+      content: String(d.content || ''),
+      timestamp: String(d.timestamp || ''),
+    }));
+}
+
+/**
+ * Append entries to a session's JSONL history file. No-op if sessionId is empty.
+ *
+ * @param {string} sessionId
+ * @param {Array<{ role: string, content: string, ts?: string }>} entries
+ * @param {string} [sessionDir]
+ */
+function appendHistory(sessionId, entries, sessionDir) {
+  if (!sessionId || !entries || !entries.length) return;
+  const file = sessionFilePath(sessionId, sessionDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const lines = entries.map(e =>
+    JSON.stringify({
+      role: e.role,
+      content: e.content,
+      timestamp: e.ts || new Date().toISOString(),
+    })
+  );
+  fs.appendFileSync(file, lines.join('\n') + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Env parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse AGENT_ATTACHMENTS JSON. Returns [] on parse failure.
+ * @param {string} raw
+ * @returns {Attachment[]}
+ */
+function parseAttachments(raw) {
+  if (!raw) return [];
+  let items;
+  try {
+    items = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(items)) return [];
+  /** @type {Attachment[]} */
+  const out = [];
+  for (const it of items) {
+    if (!it || typeof it !== 'object') continue;
+    const t = String(it.type || '');
+    const u = String(it.url || '');
+    if (!t || !u) continue;
+    out.push({ type: t, url: u, name: String(it.name || '') });
+  }
+  return out;
+}
+
+function contextFromEnv() {
+  return {
+    message: process.env.AGENT_MESSAGE || '',
+    sessionId: process.env.AGENT_SESSION_ID || '',
+    sessionName: process.env.AGENT_SESSION_NAME || 'default',
+    fromUser: process.env.AGENT_FROM_USER || '',
+    streaming: (process.env.AGENT_STREAMING || '1') !== '0',
+    protocolVersion: process.env.AGENT_PROTOCOL_VERSION || PROTOCOL_VERSION,
+    imageUrl: process.env.AGENT_IMAGE_URL || '',
+    fileUrl: process.env.AGENT_FILE_URL || '',
+    attachments: parseAttachments(process.env.AGENT_ATTACHMENTS || ''),
+
+    /** Send a streaming chunk to the user immediately. */
+    sendPartial(text) {
+      if (!text) return;
+      process.stdout.write(`AGENT_PARTIAL:${JSON.stringify(text)}\n`);
+    },
+
+    /** Send an error message to the user. Honored regardless of streaming mode. */
+    sendError(text) {
+      if (!text) return;
+      process.stdout.write(`AGENT_ERROR:${JSON.stringify(text)}\n`);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// createProfile — main entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a handler as an AgentProc-compliant process.
+ *
+ * @param {(ctx: AgentContext) => Promise<AgentResult | string | void>} handler
+ */
+function createProfile(handler) {
+  const ctx = contextFromEnv();
+
+  Promise.resolve()
+    .then(() => handler(ctx))
+    .then(result => {
+      if (result == null) {
+        // Handler signalled everything via sendPartial / sendError itself.
+        process.exit(0);
+      }
+      const response = typeof result === 'string' ? result : (result.response || '');
+      const newSessionId = typeof result === 'string' ? undefined : result.sessionId;
+
+      if (newSessionId) {
+        process.stdout.write(`AGENT_SESSION:${newSessionId}\n`);
+      }
+      if (response) {
+        process.stdout.write(response);
+        if (!response.endsWith('\n')) process.stdout.write('\n');
+      }
+      process.exit(0);
+    })
+    .catch(err => {
+      // Match Python SDK behavior: a ProtocolError-like object signals a user-facing error.
+      if (err && err.isProtocolError) {
+        const msg = String(err.message || 'unknown error');
+        process.stdout.write(`AGENT_ERROR:${JSON.stringify(msg)}\n`);
+        process.exit(1);
+      }
+      process.stderr.write(`[agentproc] handler error: ${err && err.stack || err}\n`);
+      process.exit(1);
+    });
+}
+
+/**
+ * Throw this to surface a user-readable error via AGENT_ERROR.
+ * @param {string} message
+ * @returns {Promise<never>}
+ */
+async function protocolError(message) {
+  const err = new Error(message || 'unknown error');
+  err.isProtocolError = true;
+  throw err;
+}
+
+module.exports = {
+  createProfile,
+  loadHistory,
+  appendHistory,
+  sessionFilePath,
+  parseAttachments,
+  protocolError,
+  PROTOCOL_VERSION,
+};

package/src/index.test.js

@@ -0,0 +1,356 @@
+'use strict';
+/**
+ * Tests for agentproc.
+ *
+ * Run with: `node --test src/index.test.js`
+ *
+ * Strategy: the SDK calls process.exit() at the end of createProfile, which is
+ * hard to test in-process. So we split tests into two groups:
+ *
+ *   1. Pure-function tests (loadHistory, appendHistory, sessionFilePath,
+ *      parseAttachments) — run in-process, assert on return values.
+ *
+ *   2. createProfile end-to-end tests — spawn a child node process that sets
+ *      AGENT_* env vars, requires the SDK, and writes the captured output
+ *      back to us over stdout (we intercept process.exit via a small shim).
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const SDK = require('./index.js');
+const SDK_PATH = require.resolve('./index.js');
+
+// ---------------------------------------------------------------------------
+// 1. Pure-function tests
+// ---------------------------------------------------------------------------
+
+describe('sessionFilePath', () => {
+  test('returns a path under the default session dir', () => {
+    const p = SDK.sessionFilePath('abc123');
+    assert.match(p, /\.agentproc[\\/]+sessions[\\/]+abc123\.jsonl$/);
+  });
+
+  test('respects the sessionDir argument', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-test-'));
+    const p = SDK.sessionFilePath('xyz', tmp);
+    assert.strictEqual(p, path.join(tmp, 'xyz.jsonl'));
+  });
+
+  test('throws on empty sessionId', () => {
+    assert.throws(() => SDK.sessionFilePath(''), /sessionId must be non-empty/);
+  });
+});
+
+describe('loadHistory / appendHistory', () => {
+  test('loadHistory returns [] for empty sessionId', () => {
+    assert.deepStrictEqual(SDK.loadHistory(''), []);
+  });
+
+  test('loadHistory returns [] when file does not exist', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-test-'));
+    assert.deepStrictEqual(SDK.loadHistory('never-existed', tmp), []);
+  });
+
+  test('appendHistory → loadHistory round trip', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-test-'));
+    SDK.appendHistory('s1', [
+      { role: 'user', content: 'hello' },
+      { role: 'assistant', content: 'hi' },
+    ], tmp);
+    const loaded = SDK.loadHistory('s1', tmp);
+    assert.strictEqual(loaded.length, 2);
+    assert.strictEqual(loaded[0].role, 'user');
+    assert.strictEqual(loaded[0].content, 'hello');
+    assert.ok(loaded[0].timestamp, 'timestamp should be set');
+    assert.strictEqual(loaded[1].role, 'assistant');
+  });
+
+  test('appendHistory is no-op when sessionId is empty', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-test-'));
+    SDK.appendHistory('', [{ role: 'user', content: 'x' }], tmp);
+    // No file created.
+    assert.strictEqual(fs.readdirSync(tmp).length, 0);
+  });
+
+  test('appendHistory is no-op when entries is empty', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-test-'));
+    SDK.appendHistory('s1', [], tmp);
+    assert.strictEqual(fs.readdirSync(tmp).length, 0);
+  });
+
+  test('loadHistory skips malformed JSON lines', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-test-'));
+    const file = path.join(tmp, 's1.jsonl');
+    fs.writeFileSync(file, [
+      JSON.stringify({ role: 'user', content: 'ok', timestamp: 't1' }),
+      'this is not json',
+      JSON.stringify({ role: 'assistant', content: 'still ok', timestamp: 't2' }),
+    ].join('\n') + '\n');
+    const loaded = SDK.loadHistory('s1', tmp);
+    assert.strictEqual(loaded.length, 2);
+  });
+});
+
+describe('parseAttachments', () => {
+  test('returns [] for empty string', () => {
+    assert.deepStrictEqual(SDK.parseAttachments(''), []);
+  });
+
+  test('returns [] for malformed JSON', () => {
+    assert.deepStrictEqual(SDK.parseAttachments('not json'), []);
+  });
+
+  test('returns [] for non-array JSON', () => {
+    assert.deepStrictEqual(SDK.parseAttachments('{"type":"image"}'), []);
+  });
+
+  test('parses a valid array', () => {
+    const raw = JSON.stringify([
+      { type: 'image', url: 'https://x/a.png', name: 'a.png' },
+      { type: 'file', url: 'https://y/b.pdf' },
+    ]);
+    const out = SDK.parseAttachments(raw);
+    assert.strictEqual(out.length, 2);
+    assert.strictEqual(out[0].type, 'image');
+    assert.strictEqual(out[0].name, 'a.png');
+    assert.strictEqual(out[1].type, 'file');
+    assert.strictEqual(out[1].name, '');
+  });
+
+  test('skips entries missing type or url', () => {
+    const raw = JSON.stringify([
+      { type: 'image' }, // missing url
+      { url: 'https://x' }, // missing type
+      { type: 'file', url: 'https://y' }, // ok
+    ]);
+    const out = SDK.parseAttachments(raw);
+    assert.strictEqual(out.length, 1);
+    assert.strictEqual(out[0].type, 'file');
+  });
+});
+
+test('PROTOCOL_VERSION is "0.1"', () => {
+  assert.strictEqual(SDK.PROTOCOL_VERSION, '0.1');
+});
+
+// ---------------------------------------------------------------------------
+// 2. createProfile end-to-end tests
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a child node process that:
+ *   - sets AGENT_* env vars
+ *   - loads the SDK
+ *   - runs the given handler body
+ *
+ * The SDK calls process.exit(); Node flushes stdout on exit, so we observe
+ * the full output via the close event. No process.exit stubbing needed.
+ *
+ * Returns a promise resolving to { stdout, stderr, code }.
+ */
+function runAgent(env, handlerSrc) {
+  return new Promise((resolve, reject) => {
+    const bootstrap = `
+      const sdk = require(${JSON.stringify(SDK_PATH)});
+      (${handlerSrc})(sdk).catch(e => {
+        process.stderr.write('HANDLER_ERROR: ' + (e && e.stack || e) + '\\n');
+        if (!process.exitCode) process.exitCode = 1;
+      });
+    `;
+    const child = spawn(process.execPath, ['-e', bootstrap], {
+      env: { ...process.env, ...env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', d => { stdout += d.toString(); });
+    child.stderr.on('data', d => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', code => resolve({ stdout, stderr, code }));
+  });
+}
+
+describe('createProfile end-to-end', () => {
+  test('returns a plain string → emitted as reply body', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '0' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          return 'You said: ' + ctx.message;
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0, 'stderr=' + r.stderr);
+    assert.ok(r.stdout.includes('You said: hi\n'), 'stdout=' + JSON.stringify(r.stdout));
+  });
+
+  test('returns AgentResult with session_id → AGENT_SESSION: line emitted', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '0' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          return { response: 'ok', sessionId: 'sess-123' };
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0, 'stderr=' + r.stderr);
+    assert.ok(r.stdout.includes('AGENT_SESSION:sess-123\n'), 'stdout=' + JSON.stringify(r.stdout));
+    assert.ok(r.stdout.includes('ok\n'));
+  });
+
+  test('sendPartial emits AGENT_PARTIAL: lines', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '1' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          await ctx.sendPartial('chunk 1');
+          await ctx.sendPartial('chunk 2');
+          return { response: '', sessionId: 's1' };
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0, 'stderr=' + r.stderr);
+    assert.ok(r.stdout.includes('AGENT_PARTIAL:"chunk 1"\n'), 'stdout=' + JSON.stringify(r.stdout));
+    assert.ok(r.stdout.includes('AGENT_PARTIAL:"chunk 2"\n'));
+    assert.ok(r.stdout.includes('AGENT_SESSION:s1\n'));
+  });
+
+  test('sendError emits AGENT_ERROR: line', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '0' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          await ctx.sendError('rate limited; retry in 60s');
+          return { response: 'should be discarded by bridge', sessionId: '' };
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0, 'stderr=' + r.stderr);
+    assert.ok(
+      r.stdout.includes('AGENT_ERROR:"rate limited; retry in 60s"\n'),
+      'stdout=' + JSON.stringify(r.stdout)
+    );
+  });
+
+  test('protocolError surfaces as AGENT_ERROR + exit 1', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '0' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          throw await sdk.protocolError('bad input');
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 1, 'stdout=' + r.stdout + ' stderr=' + r.stderr);
+    assert.ok(r.stdout.includes('AGENT_ERROR:"bad input"\n'), 'stdout=' + JSON.stringify(r.stdout));
+  });
+
+  test('handler exception → exit 1, stderr has stack', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '0' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          throw new Error('boom');
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 1);
+    assert.ok(r.stderr.includes('boom'), 'stderr=' + JSON.stringify(r.stderr));
+    assert.ok(!r.stdout.includes('AGENT_ERROR'), 'should NOT emit AGENT_ERROR for generic errors');
+  });
+
+  test('context carries AGENT_* env vars', async () => {
+    const r = await runAgent(
+      {
+        AGENT_MESSAGE: 'hello',
+        AGENT_SESSION_ID: 'prev-sess',
+        AGENT_SESSION_NAME: 'work',
+        AGENT_FROM_USER: 'u123',
+        AGENT_STREAMING: '0',
+        AGENT_IMAGE_URL: 'https://x/img.png',
+        AGENT_FILE_URL: 'https://y/file.pdf',
+        AGENT_ATTACHMENTS: JSON.stringify([
+          { type: 'image', url: 'https://z/1.png' },
+          { type: 'file', url: 'https://z/2.pdf', name: '2.pdf' },
+        ]),
+      },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          return JSON.stringify({
+            msg: ctx.message,
+            sid: ctx.sessionId,
+            sname: ctx.sessionName,
+            from: ctx.fromUser,
+            stream: ctx.streaming,
+            img: ctx.imageUrl,
+            file: ctx.fileUrl,
+            atts: ctx.attachments,
+          });
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0, 'stderr=' + r.stderr);
+    const parsed = JSON.parse(r.stdout.trim());
+    assert.strictEqual(parsed.msg, 'hello');
+    assert.strictEqual(parsed.sid, 'prev-sess');
+    assert.strictEqual(parsed.sname, 'work');
+    assert.strictEqual(parsed.from, 'u123');
+    assert.strictEqual(parsed.stream, false);
+    assert.strictEqual(parsed.img, 'https://x/img.png');
+    assert.strictEqual(parsed.file, 'https://y/file.pdf');
+    assert.strictEqual(parsed.atts.length, 2);
+    assert.strictEqual(parsed.atts[0].type, 'image');
+    assert.strictEqual(parsed.atts[1].name, '2.pdf');
+  });
+
+  test('malformed AGENT_ATTACHMENTS → attachments = []', async () => {
+    const r = await runAgent(
+      {
+        AGENT_MESSAGE: 'hi',
+        AGENT_STREAMING: '0',
+        AGENT_ATTACHMENTS: 'not json',
+      },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          return JSON.stringify({ atts: ctx.attachments });
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0);
+    assert.deepStrictEqual(JSON.parse(r.stdout.trim()).atts, []);
+  });
+
+  test('handler can return undefined (signaled everything via partials)', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '1' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          await ctx.sendPartial('only partial');
+          // no return → undefined
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0, 'stderr=' + r.stderr);
+    assert.ok(r.stdout.includes('AGENT_PARTIAL:"only partial"\n'));
+    // No trailing garbage
+    assert.ok(!r.stdout.includes('undefined'));
+  });
+
+  test('default protocolVersion is 0.1', async () => {
+    const r = await runAgent(
+      { AGENT_MESSAGE: 'hi', AGENT_STREAMING: '0' },
+      `(async (sdk) => {
+        sdk.createProfile(async (ctx) => {
+          return 'pv=' + ctx.protocolVersion;
+        });
+      })`
+    );
+    assert.strictEqual(r.code, 0);
+    assert.ok(r.stdout.includes('pv=0.1'));
+  });
+});