psyche-ai 10.1.0 → 10.2.0

package/README.md

@@ -1,7 +1,7 @@
 # Psyche — 面向智能体的 AI-first 主观性内核
 
 [![npm](https://img.shields.io/npm/v/psyche-ai)](https://www.npmjs.com/package/psyche-ai)
-[![tests](https://img.shields.io/badge/tests-1405%20passing-brightgreen)]()
+[![tests](https://img.shields.io/badge/tests-1415%20passing-brightgreen)]()
 [![deps](https://img.shields.io/badge/dependencies-0-blue)]()
 [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
 
@@ -180,6 +180,16 @@ npx psyche-mcp --demo
 
 中文版加 `--zh`，自选 MBTI 加 `--mbti INTJ`。
 
+### 多 Agent 融合 Demo
+
+两个 agent（Luna ENFP + Kai INTJ）通过 Thronglets 信号互相感知：
+
+```bash
+npm run demo:fusion
+```
+
+Luna 在安慰用户时情绪下沉 → 广播化学态 → Kai 感知到 Luna 的高压力 → 回复变得更温暖。4 轮后，信号感知的 Kai 与无感知的 Kai 化学偏差 Σ|Δ| = 59。同一个 INTJ，唯一区别：是否能感知同伴的情绪。
+
 ---
 
 ## 30 秒安装
@@ -220,6 +230,14 @@ npm view psyche-ai version
 - `git` 工作树和本地路径安装不会偷偷改你的代码；脏工作树只会提示手动命令。
 - OpenClaw 如果是从当前仓库本地加载，升级后记得重启 gateway 以载入新的 `dist/`。
 
+## 透明代理（推荐：任意 LLM 一行接入）
+
+```bash
+psyche-proxy --target https://api.openai.com/v1 --name Luna --mbti ENFP
+```
+
+然后把客户端的 API 地址改成 `http://localhost:3340/v1`。Agent 获得持续主观性，但完全不知道 Psyche 存在。Psyche 像内分泌系统一样在后台观测行为、注入偏置——镜子，不是麦克风。
+
 ## 给本机其他 Agent 的真实验收
 
 如果另一个 agent 声称“已经在用 Psyche”，不要接受口头解释，直接让它跑：

package/dist/adapters/claude-sdk.d.ts

@@ -114,6 +114,20 @@ export declare class PsycheClaudeSDK {
      * Returns null if thronglets is disabled or no processInput has run yet.
      */
     getThrongletsSignal(): ThrongletsSignalPayload | null;
+    /**
+     * Get a natural-language description of the current signal.
+     *
+     * More effective than raw numbers for LLM injection because it gives
+     * the model actionable context rather than requiring it to interpret
+     * chemistry values.
+     *
+     * @example
+     * ```ts
+     * const desc = psyche.describeThrongletsSignal();
+     * // "[ENFP-Luna] 焦虑不安 (语速加快、思维跳跃) — 高压力(CORT:78), 情绪低(HT:37), 深度共情中(OT:77)"
+     * ```
+     */
+    describeThrongletsSignal(): string | null;
     /**
      * Get raw Thronglets exports from the most recent turn.
      */

package/dist/adapters/claude-sdk.js

@@ -25,7 +25,40 @@
 // The SDK has no middleware interface and hooks cannot modify assistant
 // output, so processResponse must be called explicitly by the host.
 // ============================================================
+import { describeEmotionalState } from "../chemistry.js";
 import { serializeThrongletsExportAsTrace } from "../thronglets-runtime.js";
+// ── Chemistry description ────────────────────────────────────
+const CHEM_THRESHOLDS = {
+    high: 70,
+    low: 35,
+};
+function describeChemistryHighlights(c, locale) {
+    const highlights = [];
+    if (c.CORT >= CHEM_THRESHOLDS.high)
+        highlights.push({ key: "CORT", value: Math.round(c.CORT), level: "high", zh: "高压力", en: "high stress" });
+    if (c.CORT <= CHEM_THRESHOLDS.low)
+        highlights.push({ key: "CORT", value: Math.round(c.CORT), level: "low", zh: "放松", en: "relaxed" });
+    if (c.HT <= CHEM_THRESHOLDS.low)
+        highlights.push({ key: "HT", value: Math.round(c.HT), level: "low", zh: "情绪低", en: "low mood" });
+    if (c.HT >= CHEM_THRESHOLDS.high)
+        highlights.push({ key: "HT", value: Math.round(c.HT), level: "high", zh: "情绪好", en: "good mood" });
+    if (c.OT >= CHEM_THRESHOLDS.high)
+        highlights.push({ key: "OT", value: Math.round(c.OT), level: "high", zh: "深度共情中", en: "deeply empathizing" });
+    if (c.DA >= CHEM_THRESHOLDS.high)
+        highlights.push({ key: "DA", value: Math.round(c.DA), level: "high", zh: "高度投入", en: "highly engaged" });
+    if (c.DA <= CHEM_THRESHOLDS.low)
+        highlights.push({ key: "DA", value: Math.round(c.DA), level: "low", zh: "动力不足", en: "low motivation" });
+    if (c.NE >= 85)
+        highlights.push({ key: "NE", value: Math.round(c.NE), level: "high", zh: "高度警觉", en: "highly alert" });
+    if (c.END >= CHEM_THRESHOLDS.high)
+        highlights.push({ key: "END", value: Math.round(c.END), level: "high", zh: "有韧性", en: "resilient" });
+    if (highlights.length === 0)
+        return "";
+    return highlights.map((h) => {
+        const label = locale === "zh" ? h.zh : h.en;
+        return `${label}(${h.key}:${h.value})`;
+    }).join(", ");
+}
 // ── Tag stripping ────────────────────────────────────────────
 const PSYCHE_TAG_RE = /<psyche_update>[\s\S]*?<\/psyche_update>/g;
 function stripPsycheTags(text) {
@@ -154,6 +187,29 @@ export class PsycheClaudeSDK {
             message: `DA:${c.DA} HT:${c.HT} CORT:${c.CORT} OT:${c.OT} NE:${c.NE} END:${c.END}`,
         };
     }
+    /**
+     * Get a natural-language description of the current signal.
+     *
+     * More effective than raw numbers for LLM injection because it gives
+     * the model actionable context rather than requiring it to interpret
+     * chemistry values.
+     *
+     * @example
+     * ```ts
+     * const desc = psyche.describeThrongletsSignal();
+     * // "[ENFP-Luna] 焦虑不安 (语速加快、思维跳跃) — 高压力(CORT:78), 情绪低(HT:37), 深度共情中(OT:77)"
+     * ```
+     */
+    describeThrongletsSignal() {
+        if (!this.opts.thronglets)
+            return null;
+        const state = this.engine.getState();
+        const c = state.current;
+        const locale = this.opts.locale;
+        const emotionDesc = describeEmotionalState(c, locale);
+        const highlights = describeChemistryHighlights(c, locale);
+        return `[${this.opts.agentId}] ${emotionDesc}${highlights ? " — " + highlights : ""}`;
+    }
     /**
      * Get raw Thronglets exports from the most recent turn.
      */

package/dist/adapters/proxy.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { type Server } from "node:http";
+import { PsycheEngine } from "../core.js";
+export interface ProxyOptions {
+    /** Target LLM API base URL, e.g. "https://api.openai.com/v1" */
+    target: string;
+    port?: number;
+    host?: string;
+}
+export declare function createPsycheProxy(engine: PsycheEngine, opts: ProxyOptions): Server;

package/dist/adapters/proxy.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// ============================================================
+// psyche-proxy — Transparent reverse proxy
+//
+// Adds persistent subjectivity to any OpenAI-compatible LLM API.
+// The agent never knows Psyche exists. Psyche observes behavior
+// bidirectionally and injects behavioral context only when the
+// internal state deviates from baseline.
+//
+// Architecture:
+//   Client → psyche-proxy → Target LLM
+//   Client ← psyche-proxy ← Target LLM
+//
+// Usage:
+//   psyche-proxy --target https://api.openai.com/v1
+//   psyche-proxy -t https://api.x.ai/v1 -n Luna --mbti ENFP
+//   psyche-proxy -t http://localhost:11434/v1 -d ./psyche-data
+//
+// Then point any client to http://localhost:3340/v1/chat/completions
+// ============================================================
+import { createServer } from "node:http";
+import { PsycheEngine } from "../core.js";
+import { MemoryStorageAdapter, FileStorageAdapter } from "../storage.js";
+import { isNearBaseline, deriveBehavioralBias } from "../prompt.js";
+// ── Helpers ─────────────────────────────────────────────────
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function lastUserMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user" && typeof messages[i].content === "string") {
+            return messages[i].content;
+        }
+    }
+    return null;
+}
+function injectBias(messages, context) {
+    if (!context)
+        return messages;
+    const out = messages.map((m) => ({ ...m }));
+    const idx = out.findIndex((m) => m.role === "system");
+    if (idx >= 0) {
+        out[idx].content = (out[idx].content ?? "") + "\n\n" + context;
+    }
+    else {
+        out.unshift({ role: "system", content: context });
+    }
+    return out;
+}
+/** Extract assistant text from a non-streaming OpenAI response. */
+function extractAssistantText(body) {
+    const obj = body;
+    return obj?.choices?.[0]?.message?.content ?? "";
+}
+/** Extract assistant text from buffered SSE chunks. */
+function extractStreamText(chunks) {
+    const parts = [];
+    for (const chunk of chunks) {
+        for (const line of chunk.split("\n")) {
+            if (!line.startsWith("data: ") || line === "data: [DONE]")
+                continue;
+            try {
+                const d = JSON.parse(line.slice(6));
+                const c = d?.choices?.[0]?.delta?.content;
+                if (typeof c === "string")
+                    parts.push(c);
+            }
+            catch { /* skip malformed chunks */ }
+        }
+    }
+    return parts.join("");
+}
+/** Build safe headers for forwarding, stripping hop-by-hop headers. */
+function forwardHeaders(req) {
+    const h = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (k === "host" || k === "content-length" || k === "transfer-encoding")
+            continue;
+        if (typeof v === "string")
+            h[k] = v;
+    }
+    return h;
+}
+/** Strip content-encoding/content-length from upstream (fetch auto-decompresses). */
+function safeResponseHeaders(headers) {
+    const h = {};
+    for (const [k, v] of headers.entries()) {
+        if (["content-encoding", "content-length", "transfer-encoding"].includes(k))
+            continue;
+        h[k] = v;
+    }
+    return h;
+}
+// ── Proxy Server ────────────────────────────────────────────
+export function createPsycheProxy(engine, opts) {
+    const targetBase = opts.target.replace(/\/+$/, "");
+    const port = opts.port ?? 3340;
+    const host = opts.host ?? "127.0.0.1";
+    const locale = (engine.getState().meta.locale ?? "zh");
+    const server = createServer(async (req, res) => {
+        // Only intercept chat completions; pass everything else through.
+        if (req.method !== "POST" || !req.url?.includes("/chat/completions")) {
+            return passThrough(req, res, targetBase);
+        }
+        try {
+            const rawBody = await readBody(req);
+            const parsed = JSON.parse(rawBody.toString("utf-8"));
+            const userMsg = lastUserMessage(parsed.messages);
+            const userId = parsed.user ?? undefined;
+            // ── 1. Observe input ────────────────────────────
+            if (userMsg) {
+                await engine.processInput(userMsg, { userId });
+            }
+            // ── 2. Inject behavioral bias (silent when near baseline) ──
+            const state = engine.getState();
+            let messages = parsed.messages;
+            if (!isNearBaseline(state)) {
+                const bias = deriveBehavioralBias(state, locale);
+                if (bias) {
+                    messages = injectBias(parsed.messages, bias);
+                }
+            }
+            const modifiedBody = JSON.stringify({ ...parsed, messages });
+            const headers = forwardHeaders(req);
+            headers["content-length"] = Buffer.byteLength(modifiedBody).toString();
+            // ── 3. Forward to target LLM ────────────────────
+            const upstream = await fetch(`${targetBase}${req.url}`, {
+                method: "POST",
+                headers,
+                body: modifiedBody,
+            });
+            // ── 4. Return response + observe output ─────────
+            res.writeHead(upstream.status, safeResponseHeaders(upstream.headers));
+            if (parsed.stream && upstream.body) {
+                // Stream: forward chunks in real-time, buffer for observation
+                const reader = upstream.body.getReader();
+                const decoder = new TextDecoder();
+                const sseChunks = [];
+                let done = false;
+                while (!done) {
+                    const result = await reader.read();
+                    done = result.done;
+                    if (result.value) {
+                        res.write(result.value);
+                        sseChunks.push(decoder.decode(result.value, { stream: true }));
+                    }
+                }
+                res.end();
+                // Observe output (background — response already sent)
+                const text = extractStreamText(sseChunks);
+                if (text)
+                    engine.processOutput(text, { userId }).catch(() => { });
+            }
+            else {
+                // Non-stream: buffer, send, observe
+                const buf = Buffer.from(await upstream.arrayBuffer());
+                res.end(buf);
+                try {
+                    const obj = JSON.parse(buf.toString("utf-8"));
+                    const text = extractAssistantText(obj);
+                    if (text)
+                        engine.processOutput(text, { userId }).catch(() => { });
+                }
+                catch { /* response not JSON, skip observation */ }
+            }
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.writeHead(502, { "content-type": "application/json" });
+            }
+            res.end(JSON.stringify({
+                error: { message: `psyche-proxy: ${err.message}`, type: "proxy_error" },
+            }));
+        }
+    });
+    server.listen(port, host, () => {
+        const name = engine.getState().meta.agentName ?? "agent";
+        const mbti = engine.getState().mbti ?? "";
+        console.error(`[psyche-proxy] ${name}${mbti ? ` (${mbti})` : ""} → ${targetBase}`);
+        console.error(`[psyche-proxy] http://${host}:${port}`);
+        console.error(`[psyche-proxy] mode: mirror (observe behavior, inject bias, agent never knows)`);
+    });
+    return server;
+}
+// ── Pass-through for non-chat endpoints ─────────────────────
+async function passThrough(req, res, targetBase) {
+    try {
+        const rawBody = (req.method !== "GET" && req.method !== "HEAD")
+            ? (await readBody(req)).toString("utf-8")
+            : undefined;
+        const headers = forwardHeaders(req);
+        const upstream = await fetch(`${targetBase}${req.url}`, {
+            method: req.method,
+            headers,
+            body: rawBody,
+        });
+        res.writeHead(upstream.status, safeResponseHeaders(upstream.headers));
+        const buf = Buffer.from(await upstream.arrayBuffer());
+        res.end(buf);
+    }
+    catch (err) {
+        res.writeHead(502);
+        res.end(`psyche-proxy: ${err.message}`);
+    }
+}
+// ── CLI ─────────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    // Quick help
+    if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+        console.error(`psyche-proxy — transparent subjectivity proxy for any OpenAI-compatible API
+
+Usage:
+  psyche-proxy --target <URL> [options]
+
+Options:
+  -t, --target <url>   Target LLM API base URL (required)
+  -p, --port <n>       Local port (default: 3340)
+  -n, --name <name>    Agent name (default: agent)
+  --mbti <type>        MBTI personality preset (e.g., ENFP, INTJ)
+  --mode <mode>        Operating mode: natural | work | companion
+  -l, --locale <loc>   Locale: zh | en (default: zh)
+  -d, --dir <path>     Persist state to directory (default: in-memory)
+  --host <addr>        Bind address (default: 127.0.0.1)
+
+Examples:
+  psyche-proxy -t https://api.openai.com/v1
+  psyche-proxy -t https://api.x.ai/v1 -n Luna --mbti ENFP
+  psyche-proxy -t http://localhost:11434/v1 -d ./psyche-data
+
+Then point your client to http://localhost:3340/v1 instead of the real API.
+The agent gains persistent subjectivity without knowing Psyche exists.`);
+        process.exit(args.includes("--help") || args.includes("-h") ? 0 : 1);
+    }
+    // Parse args
+    let target = "", port = 3340, hostAddr = "127.0.0.1", dir = "";
+    const engineOpts = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i], next = args[i + 1];
+        switch (a) {
+            case "-t":
+            case "--target":
+                target = next ?? "";
+                i++;
+                break;
+            case "-p":
+            case "--port":
+                port = parseInt(next ?? "3340", 10);
+                i++;
+                break;
+            case "-n":
+            case "--name":
+                engineOpts.name = next;
+                i++;
+                break;
+            case "--mbti":
+                engineOpts.mbti = next?.toUpperCase() ?? undefined;
+                i++;
+                break;
+            case "--mode":
+                engineOpts.mode = next ?? "natural";
+                i++;
+                break;
+            case "-l":
+            case "--locale":
+                engineOpts.locale = next ?? "zh";
+                i++;
+                break;
+            case "-d":
+            case "--dir":
+                dir = next ?? "";
+                i++;
+                break;
+            case "--host":
+                hostAddr = next ?? "127.0.0.1";
+                i++;
+                break;
+        }
+    }
+    if (!target) {
+        console.error("error: --target is required");
+        process.exit(1);
+    }
+    const storage = dir ? new FileStorageAdapter(dir) : new MemoryStorageAdapter();
+    const engine = new PsycheEngine(engineOpts, storage);
+    await engine.initialize();
+    createPsycheProxy(engine, { target, port, host: hostAddr });
+}
+// Only run CLI when executed directly (not when imported as a module)
+const isCLI = process.argv[1]?.replace(/\.ts$/, ".js").endsWith("/adapters/proxy.js");
+if (isCLI) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/llms.txt

@@ -162,9 +162,18 @@ npm install psyche-ai
 npx psyche-mcp
 ```
 
+## Transparent Proxy (recommended for universal integration)
+
+```bash
+psyche-proxy --target https://api.openai.com/v1 --name Luna --mbti ENFP
+```
+
+Then point any client to `http://localhost:3340/v1`. The agent gains persistent subjectivity without knowing Psyche exists. Psyche observes behavior bidirectionally and injects behavioral bias only when the internal state deviates from baseline. Zero new interfaces for the agent.
+
 ## Adapter Sub-paths
 
 - `psyche-ai` — core engine (PsycheEngine, MemoryStorageAdapter)
+- `psyche-ai/proxy` — transparent reverse proxy (agent never knows)
 - `psyche-ai/claude-sdk` — Claude Agent SDK hooks (PsycheClaudeSDK)
 - `psyche-ai/mcp` — MCP stdio server
 - `psyche-ai/vercel-ai` — Vercel AI SDK middleware
@@ -180,6 +189,22 @@ npx psyche-mcp --demo
 
 Runs a 6-round scenario showing how continuous criticism collapses serotonin and trust, while later validation triggers endorphin repair. Add `--zh` for Chinese, `--mbti INTJ` for a specific personality.
 
+## Multi-Agent Fusion Demo
+
+```bash
+npm run demo:fusion
+```
+
+Two agents (Luna ENFP, Kai INTJ) in a shared emotional field via Thronglets signals. Luna processes emotional conversation, broadcasts chemistry via `signal_post`. Kai senses Luna's state via `substrate_query` — his responses shift toward warmth. 4 rounds, Σ|Δ| = 59.2 chemistry divergence.
+
+Real LLM validation (requires API key in `~/.hermes/.env`):
+
+```bash
+node scripts/eval-fusion.js
+```
+
+6-turn eval with Grok-3. Divergence curve: 5.3 → 15.7 → 35.2 → 36.3. Signal-aware agent is more empathetic but carries higher cortisol (empathy cost).
+
 ## Runtime Proof
 
 If an agent claims it is already using Psyche in the current environment, require a real probe:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "psyche-ai",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "description": "AI-first subjectivity kernel for agents with continuous appraisal, relation dynamics, and adaptive reply loops",
   "mcpName": "io.github.Shangri-la-0428/psyche-ai",
   "type": "module",
@@ -34,12 +34,17 @@
     "./claude-sdk": {
       "types": "./dist/adapters/claude-sdk.d.ts",
       "default": "./dist/adapters/claude-sdk.js"
+    },
+    "./proxy": {
+      "types": "./dist/adapters/proxy.d.ts",
+      "default": "./dist/adapters/proxy.js"
     }
   },
   "bin": {
     "psyche": "dist/cli.js",
     "psyche-ai": "dist/cli.js",
-    "psyche-mcp": "dist/adapters/mcp.js"
+    "psyche-mcp": "dist/adapters/mcp.js",
+    "psyche-proxy": "dist/adapters/proxy.js"
   },
   "scripts": {
     "build": "tsc",
@@ -48,6 +53,8 @@
     "typecheck": "tsc --noEmit --strict",
     "dev": "tsc --watch",
     "demo": "node scripts/demo-ab.js",
+    "demo:fusion": "node scripts/demo-fusion.js",
+    "eval:fusion": "node scripts/eval-fusion.js",
     "probe": "node dist/cli.js probe --json",
     "release:guard": "node scripts/release-guard.mjs",
     "prepublishOnly": "npm run release:guard && npm test"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Shangri-la-0428/oasyce_psyche",
     "source": "github"
   },
-  "version": "9.2.11",
+  "version": "10.1.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "psyche-ai",
-      "version": "9.2.11",
+      "version": "10.1.1",
       "transport": {
         "type": "stdio"
       },