ilink-bridge-profile 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# ilink-bridge-profile (Node.js)
+
+Node.js SDK for writing [iLink Hub Bridge](../../docs/bridge/profile-spec.md) profile handlers.
+
+Implements the **P0 exec protocol** — reads `ILINK_*` env vars injected by the bridge,
+calls your async handler, writes P0-formatted output to stdout. Works on macOS, Linux, and Windows.
+
+## Install
+
+```bash
+npm install ilink-bridge-profile
+```
+
+## Quick start
+
+```js
+// my-profile.js
+const { createProfile } = require('ilink-bridge-profile');
+
+createProfile(async ({ message, sessionId, sessionName }) => {
+  // call any LLM API here
+  const reply = await myLLM(message);
+  return { response: reply };
+});
+```
+
+Configure in `ilink-hub-bridge.yaml`:
+
+```yaml
+profiles:
+  my-ai:
+    command: node
+    args: [/path/to/my-profile.js]
+    stdin: none
+    timeout_secs: 120
+```
+
+## With session continuity
+
+```js
+const { createProfile, loadHistory, appendHistory } = require('ilink-bridge-profile');
+
+createProfile(async ({ message, sessionId }) => {
+  const history = loadHistory(sessionId);
+
+  const messages = [
+    ...history.map(e => ({ role: e.role, content: e.content })),
+    { role: 'user', content: message },
+  ];
+
+  const reply = await callOpenAI(messages);
+
+  appendHistory(sessionId, [
+    { role: 'user', content: message },
+    { role: 'assistant', content: reply },
+  ]);
+
+  return { response: reply, sessionId };
+});
+```
+
+History is stored in `~/.ilink-hub/sessions/<sessionId>.jsonl` (one JSON object per line).
+
+## API
+
+### `createProfile(handler)`
+
+Runs the P0 protocol loop: reads env vars → calls `handler(ctx)` → writes stdout → exits.
+
+**`ctx`** fields:
+| Field | Env var | Description |
+|-------|---------|-------------|
+| `message` | `ILINK_MESSAGE` | User message text |
+| `sessionId` | `ILINK_SESSION_ID` | Hub-persisted backend session UUID |
+| `sessionName` | `ILINK_SESSION_NAME` | Human-readable session name |
+| `fromUser` | `ILINK_FROM_USER` | Sender user ID |
+| `contextToken` | `ILINK_CONTEXT_TOKEN` | Hub context token |
+
+**Return value**: `{ response: string, sessionId?: string }` or plain `string`.
+
+### `loadHistory(sessionId, sessionDir?)`
+
+Load conversation history from `~/.ilink-hub/sessions/<sessionId>.jsonl`.
+
+### `appendHistory(sessionId, entries, sessionDir?)`
+
+Append `[{ role, content, ts? }]` entries to the JSONL history file.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "ilink-bridge-profile",
+  "version": "0.1.0",
+  "description": "iLink Hub Bridge Profile SDK — write one async function, get a cross-platform P0-compliant profile",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "node --test src/index.test.js"
+  },
+  "keywords": ["ilink-hub", "bridge", "profile", "claude", "weixin"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,54 @@
+export interface ProfileContext {
+  /** User message text (ILINK_MESSAGE) */
+  message: string;
+  /** Hub-persisted backend session UUID (ILINK_SESSION_ID) */
+  sessionId: string;
+  /** Human-readable session name (ILINK_SESSION_NAME) */
+  sessionName: string;
+  /** Sender user ID (ILINK_FROM_USER) */
+  fromUser: string;
+  /** Hub context token (ILINK_CONTEXT_TOKEN) */
+  contextToken: string;
+}
+
+export interface ProfileResult {
+  /** Reply text to send back to the WeChat user */
+  response: string;
+  /** New backend session ID to persist (optional) */
+  sessionId?: string;
+}
+
+export type ProfileHandler = (
+  ctx: ProfileContext
+) => Promise<ProfileResult | string>;
+
+/**
+ * Run a profile handler following the P0 exec protocol.
+ * Reads ILINK_* env vars, calls `handler`, writes P0 stdout, then exits.
+ */
+export function createProfile(handler: ProfileHandler): void;
+
+export interface HistoryEntry {
+  role: 'user' | 'assistant' | string;
+  content: string;
+  ts: string;
+}
+
+/**
+ * Load conversation history for a session from its JSONL file.
+ * Returns an empty array if the file does not exist.
+ */
+export function loadHistory(sessionId: string, sessionDir?: string): HistoryEntry[];
+
+/**
+ * Append entries to a session's JSONL history file.
+ * Creates the file (and parent directory) if needed.
+ */
+export function appendHistory(
+  sessionId: string,
+  entries: Omit<HistoryEntry, 'ts'>[],
+  sessionDir?: string
+): void;
+
+/** Resolved path for a session JSONL file. */
+export function sessionFilePath(sessionId: string, sessionDir?: string): string;

package/src/index.js

@@ -0,0 +1,160 @@
+'use strict';
+/**
+ * ilink-bridge-profile — iLink Hub Bridge Profile SDK (Node.js)
+ *
+ * Implements the P0 exec protocol so you can write a single async handler function
+ * instead of manually reading env vars and formatting stdout.
+ *
+ * P0 contract (read by the bridge):
+ *   Input  — env vars: ILINK_MESSAGE, ILINK_SESSION_ID, ILINK_SESSION_NAME,
+ *                      ILINK_FROM_USER, ILINK_CONTEXT_TOKEN
+ *   Output — stdout: optional first line "ILINK_SESSION:<uuid>", then reply text
+ *   Exit   — 0 = success, non-zero = error
+ *
+ * @example
+ * // my-profile.js
+ * const { createProfile } = require('ilink-bridge-profile');
+ *
+ * createProfile(async ({ message, sessionId, sessionName, fromUser }) => {
+ *   const reply = await myAI(message);
+ *   return { response: reply, sessionId: newSessionId };
+ * });
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// ---------------------------------------------------------------------------
+// Context — passed to the handler function
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} ProfileContext
+ * @property {string} message       - User message text (ILINK_MESSAGE)
+ * @property {string} sessionId     - Hub-persisted backend session UUID (ILINK_SESSION_ID)
+ * @property {string} sessionName   - Human-readable session name (ILINK_SESSION_NAME)
+ * @property {string} fromUser      - Sender user ID (ILINK_FROM_USER)
+ * @property {string} contextToken  - Hub context token (ILINK_CONTEXT_TOKEN)
+ */
+
+/**
+ * @typedef {Object} ProfileResult
+ * @property {string}           response   - Reply text to send back to the WeChat user
+ * @property {string|undefined} sessionId  - New backend session ID to persist (optional)
+ */
+
+// ---------------------------------------------------------------------------
+// Session history helpers (optional — for SDK users calling LLM APIs directly)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default directory for session history files.
+ * @returns {string}
+ */
+function defaultSessionDir() {
+  return path.join(os.homedir(), '.ilink-hub', 'sessions');
+}
+
+/**
+ * Path for a session JSONL file, keyed by the stable session UUID.
+ * @param {string} sessionId
+ * @param {string} [sessionDir]
+ * @returns {string}
+ */
+function sessionFilePath(sessionId, sessionDir) {
+  const dir = sessionDir || defaultSessionDir();
+  return path.join(dir, `${sessionId}.jsonl`);
+}
+
+/**
+ * Load conversation history for a session from its JSONL file.
+ * Returns an empty array if the file does not exist.
+ *
+ * @param {string} sessionId
+ * @param {string} [sessionDir]
+ * @returns {{ role: string, content: string, ts: string }[]}
+ */
+function loadHistory(sessionId, sessionDir) {
+  if (!sessionId) return [];
+  const file = sessionFilePath(sessionId, sessionDir);
+  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);
+}
+
+/**
+ * Append one or more entries to a session's JSONL history file.
+ * Creates the file (and parent directory) if it does not exist.
+ *
+ * @param {string} sessionId
+ * @param {{ role: string, content: string, ts?: string }[]} entries
+ * @param {string} [sessionDir]
+ */
+function appendHistory(sessionId, entries, sessionDir) {
+  if (!sessionId || !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, ts: e.ts || new Date().toISOString() })
+  );
+  fs.appendFileSync(file, lines.join('\n') + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// createProfile — main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a profile handler following the P0 exec protocol.
+ *
+ * Reads ILINK_* env vars, invokes `handler(ctx)`, writes the P0 output to stdout,
+ * and exits the process with code 0 (success) or 1 (error).
+ *
+ * @param {(ctx: ProfileContext) => Promise<ProfileResult | string>} handler
+ *   Async function that receives the profile context and returns either:
+ *   - A `ProfileResult` object: `{ response, sessionId? }`
+ *   - A plain string (treated as the response; no session ID update)
+ */
+function createProfile(handler) {
+  const ctx = {
+    message: process.env.ILINK_MESSAGE || '',
+    sessionId: process.env.ILINK_SESSION_ID || '',
+    sessionName: process.env.ILINK_SESSION_NAME || 'default',
+    fromUser: process.env.ILINK_FROM_USER || '',
+    contextToken: process.env.ILINK_CONTEXT_TOKEN || '',
+  };
+
+  Promise.resolve()
+    .then(() => handler(ctx))
+    .then((result) => {
+      let response, newSessionId;
+
+      if (typeof result === 'string') {
+        response = result;
+      } else {
+        response = result.response || '';
+        newSessionId = result.sessionId;
+      }
+
+      // P0 output: optional session line first, then reply text
+      if (newSessionId) {
+        process.stdout.write(`ILINK_SESSION:${newSessionId}\n`);
+      }
+      process.stdout.write(response);
+      process.exit(0);
+    })
+    .catch((err) => {
+      process.stderr.write(`[ilink-hub/profile] handler error: ${err?.stack || err}\n`);
+      process.exit(1);
+    });
+}
+
+module.exports = { createProfile, loadHistory, appendHistory, sessionFilePath };

package/src/index.test.js

@@ -0,0 +1,57 @@
+'use strict';
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+const { loadHistory, appendHistory, sessionFilePath } = require('./index.js');
+
+describe('sessionFilePath', () => {
+  it('uses default dir when sessionDir omitted', () => {
+    const p = sessionFilePath('abc-123');
+    assert.ok(p.includes(path.join('.ilink-hub', 'sessions', 'abc-123.jsonl')));
+  });
+
+  it('uses custom dir when provided', () => {
+    const p = sessionFilePath('abc-123', '/tmp/test-sessions');
+    assert.equal(p, '/tmp/test-sessions/abc-123.jsonl');
+  });
+});
+
+describe('loadHistory / appendHistory', () => {
+  it('returns empty array for missing file', () => {
+    const result = loadHistory('nonexistent-uuid-xyz', '/tmp/no-such-dir');
+    assert.deepEqual(result, []);
+  });
+
+  it('round-trips history entries via JSONL', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ilink-test-'));
+    const sid = 'test-session-1';
+
+    appendHistory(sid, [
+      { role: 'user', content: 'hello', ts: '2026-01-01T00:00:00Z' },
+      { role: 'assistant', content: 'hi there', ts: '2026-01-01T00:00:01Z' },
+    ], tmpDir);
+
+    const entries = loadHistory(sid, tmpDir);
+    assert.equal(entries.length, 2);
+    assert.equal(entries[0].role, 'user');
+    assert.equal(entries[0].content, 'hello');
+    assert.equal(entries[1].role, 'assistant');
+    assert.equal(entries[1].content, 'hi there');
+  });
+
+  it('appends to existing file across multiple calls', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ilink-test-'));
+    const sid = 'test-session-2';
+
+    appendHistory(sid, [{ role: 'user', content: 'msg1' }], tmpDir);
+    appendHistory(sid, [{ role: 'assistant', content: 'reply1' }], tmpDir);
+
+    const entries = loadHistory(sid, tmpDir);
+    assert.equal(entries.length, 2);
+    assert.equal(entries[0].content, 'msg1');
+    assert.equal(entries[1].content, 'reply1');
+  });
+});