psyche-ai 11.4.0 → 11.5.2

package/README.md

@@ -1,7 +1,7 @@
 # Psyche — 赋予 AI 自我的主观性内核
 
 [![npm](https://img.shields.io/npm/v/psyche-ai)](https://www.npmjs.com/package/psyche-ai)
-[![tests](https://img.shields.io/badge/tests-1427%20passing-brightgreen)]()
+[![tests](https://img.shields.io/badge/tests-1433%20passing-brightgreen)]()
 [![deps](https://img.shields.io/badge/dependencies-0-blue)]()
 [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
 
@@ -17,6 +17,8 @@ Psyche 不是给模型贴一层“情绪 UI”。
 
 它不会额外调用模型做情绪推理。它只在本地计算自我状态（序/流/界/振四维）、关系场和调节控制，然后把结果收敛成 `SubjectivityKernel`、`ResponseContract`、`GenerationControls` 这组窄 ABI。
 
+默认就是 standalone：不需要 `Thronglets`，不需要 `oasyce-sdk`，也不需要 `Oasyce Chain`。这些只是在你要把主观连续性外化、绑定或结算时才按需接入。
+
 ## 一个项目，三个入口
 
 - **安装包**: [`psyche-ai`](https://www.npmjs.com/package/psyche-ai)
@@ -127,7 +129,7 @@ Psyche 要解决的不可压缩问题只有一个：
 不用安装任何东西，一条命令看 Psyche 如何运作：
 
 ```bash
-npx psyche-mcp --demo
+npx psyche-ai mcp --demo
 ```
 
 这会跑一个 6 轮"持续否定 → 修复"的场景。你会看到：
@@ -136,7 +138,8 @@ npx psyche-mcp --demo
   Round 1/6 │ User
   > "This report is terrible. Completely unacceptable."
 
-  stimulus: criticism
+  appraisal: identityThreat:0.64
+  legacy stimulus: criticism
 
   序   ########............  38  -12     ← coherence drops
   流   ##############......  72   +5     ← exchange increases
@@ -150,7 +153,8 @@ npx psyche-mcp --demo
   Round 3/6 │ User
   > "You don't understand me at all. Stop adding your opinion."
 
-  stimulus: conflict
+  appraisal: identityThreat:0.82
+  legacy stimulus: conflict
 
   序   ####................  22  -15     ← order collapse
   流   ################....  80  +15     ← high exchange (conflict is flow)
@@ -165,7 +169,8 @@ npx psyche-mcp --demo
   Round 6/6 │ User
   > "I'm sorry. Are you okay? I shouldn't have said that."
 
-  stimulus: validation
+  appraisal: attachmentPull:0.71
+  legacy stimulus: validation
 
   序   #############.......  65  +15     ← coherence restored
   振   ##############......  70  +12     ← resonance repair
@@ -191,24 +196,24 @@ Luna 在安慰用户时自我状态下沉 → 广播状态 → Kai 感知到 Lun
 ## 一条命令，给任何 Agent 加上主观性
 
 ```bash
-npx psyche-ai setup
+npx -y psyche-ai setup
 ```
 
-自动检测本机的 Claude Code / Claude Desktop / Cursor / Windsurf，写入配置。Claude Code 即时生效，其他重启后生效。不需要知道配置文件在哪，不需要手动编辑任何 JSON。
+自动检测本机的 Claude Code / Claude Desktop / Cursor / Windsurf / Codex，写入配置。Claude Code 即时生效，其他重启后生效。不需要知道配置文件在哪，不需要手动编辑任何 JSON 或 TOML。
 
-人格会从交互中自然涌现。如果想指定初始名字：`npx psyche-ai setup --name Luna`
+人格会从交互中自然涌现。如果想指定初始名字：`npx -y psyche-ai setup --name Luna`
 
-**覆盖非 MCP 的 Agent（Codex、自定义 agent 等）——透明代理：**
+**覆盖非 MCP 的 Agent 或直接 SDK 调用——透明代理：**
 
 ```bash
-npx psyche-ai setup --proxy -t https://api.openai.com/v1
+npx -y psyche-ai setup --proxy -t https://api.openai.com/v1
 ```
 
 启动本地代理 + 自动设置 `OPENAI_BASE_URL`。所有使用 OpenAI SDK 的程序自动走代理。Agent 完全不知道 Psyche 存在——镜子，不是麦克风。
 
 | 路径 | 覆盖范围 | 原理 |
 |------|---------|------|
-| MCP (`setup`) | Claude Code / Desktop / Cursor / Windsurf | MCP 工具协议 |
+| MCP (`setup`) | Claude Code / Desktop / Cursor / Windsurf / Codex | MCP 工具协议 |
 | Proxy (`setup --proxy`) | 任意使用 OpenAI/Anthropic SDK 的 agent | 环境变量重定向 HTTP |
 
 **验证：**`npx psyche-ai probe --json` — `ok: true` 就是在用了。
@@ -465,6 +470,14 @@ npm install psyche-ai
 ```javascript
 // Claude Agent SDK
 import { PsycheClaudeSDK } from "psyche-ai/claude-sdk";
+// 假设上面已经初始化好了 engine
+const psyche = new PsycheClaudeSDK(engine, {
+  thronglets: true,
+  context: {
+    userId: "_default",
+    agentId: "delegate-luna",
+  },
+});
 
 // Vercel AI SDK
 import { psycheMiddleware } from "psyche-ai/vercel-ai";
@@ -473,12 +486,14 @@ import { psycheMiddleware } from "psyche-ai/vercel-ai";
 import { PsycheLangChain } from "psyche-ai/langchain";
 
 // MCP（Claude Desktop / Cursor / Windsurf / Claude Code）
-// npx psyche-mcp --mbti ENFP --name Luna
+// npx psyche-ai mcp --mbti ENFP --name Luna
 
 // 任何语言（HTTP API）
 // psyche serve --port 3210
 ```
 
+如果 Claude hook runtime 已经给了 `session_id` / `agent_id`，Psyche 会直接复用它们做稀疏 Thronglets 归因，不会再偷偷发明第二层本地身份。
+
 ---
 
 ## 诊断
@@ -578,7 +593,7 @@ Psyche 核心引擎永久开源（MIT）。
 ```bash
 npm install
 npm run build
-npm test           # 1427 tests
+npm test           # 1433 tests
 npm run typecheck  # strict mode
 ```
 

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

@@ -1,5 +1,6 @@
 import type { PsycheEngine, ProcessInputResult } from "../core.js";
 import type { ThrongletsExport, ThrongletsTracePayload, WritebackSignalType } from "../types.js";
+import { type ThrongletsAmbientRuntimeOptions } from "../ambient-runtime.js";
 interface HookInput {
     session_id: string;
     cwd: string;
@@ -40,16 +41,34 @@ export interface ThrongletsSignalPayload {
     message: string;
 }
 export interface PsycheClaudeSdkOptions {
-    /** User ID for multi-user relationship tracking. Default: "default" */
+    /** User ID for relationship tracking. Default: internal shared bucket (`_default`). */
     userId?: string;
     /** Enable Thronglets trace/signal export after each turn. Default: false */
     thronglets?: boolean;
-    /** Agent identity for Thronglets traces/signals (e.g. "ENFP-Luna"). Default: engine name or "psyche" */
+    /** Agent identity for Thronglets traces/signals (e.g. "ENFP-Luna"). */
     agentId?: string;
-    /** Session ID for Thronglets trace serialization */
+    /** Session ID for Thronglets trace serialization. */
     sessionId?: string;
     /** Override locale for protocol context */
     locale?: "zh" | "en";
+    /**
+     * Optional execution context bundle.
+     *
+     * Use this when the host already knows the current delegate/session identity.
+     * Top-level `userId` / `agentId` / `sessionId` still work and take precedence.
+     */
+    context?: {
+        userId?: string;
+        agentId?: string;
+        sessionId?: string;
+    };
+    /**
+     * Optional runtime ambient-prior intake.
+     *
+     * When enabled, sparse environmental priors are fetched at turn time and
+     * passed to `processInput()` as runtime-only context.
+     */
+    ambient?: boolean | ThrongletsAmbientRuntimeOptions;
 }
 /**
  * Psyche integration for the Claude Agent SDK.
@@ -59,7 +78,9 @@ export interface PsycheClaudeSdkOptions {
  *
  * @example
  * ```ts
- * const psyche = new PsycheClaudeSDK(engine);
+ * const psyche = new PsycheClaudeSDK(engine, {
+ *   context: { userId: "_default" },
+ * });
  * const options = psyche.mergeOptions({ model: "sonnet" });
  * for await (const msg of query({ prompt: "Hey!", options })) { ... }
  * await psyche.processResponse(fullText);
@@ -70,7 +91,11 @@ export declare class PsycheClaudeSDK {
     private opts;
     private lastInputResult;
     private lastThrongletsExports;
+    private lastRuntimeContext;
     constructor(engine: PsycheEngine, opts?: PsycheClaudeSdkOptions);
+    private resolveAmbientPriors;
+    private resolveAgentId;
+    private resolveSessionId;
     /**
      * Returns the stable emotional protocol prompt.
      * Suitable for `systemPrompt.append` — changes only when locale changes.

package/dist/adapters/claude-sdk.js

@@ -9,7 +9,10 @@
 //   const engine = new PsycheEngine({ name: "Luna", mbti: "ENFP" }, new MemoryStorageAdapter());
 //   await engine.initialize();
 //
-//   const psyche = new PsycheClaudeSDK(engine);
+//   const psyche = new PsycheClaudeSDK(engine, {
+//     thronglets: true,
+//     context: { userId: "_default", agentId: "delegate-luna" },
+//   });
 //   let text = "";
 //   for await (const msg of query({ prompt: "Hey!", options: psyche.mergeOptions() })) {
 //     text += msg.content ?? "";
@@ -27,6 +30,8 @@
 // ============================================================
 import { describeEmotionalState } from "../chemistry.js";
 import { serializeThrongletsExportAsTrace } from "../thronglets-runtime.js";
+import { resolveRelationshipUserId } from "../relationship-key.js";
+import { resolveAmbientPriorsForTurn, } from "../ambient-runtime.js";
 // ── Dimension description ────────────────────────────────────
 const DIM_THRESHOLDS = {
     high: 70,
@@ -75,7 +80,9 @@ function stripPsycheTags(text) {
  *
  * @example
  * ```ts
- * const psyche = new PsycheClaudeSDK(engine);
+ * const psyche = new PsycheClaudeSDK(engine, {
+ *   context: { userId: "_default" },
+ * });
  * const options = psyche.mergeOptions({ model: "sonnet" });
  * for await (const msg of query({ prompt: "Hey!", options })) { ... }
  * await psyche.processResponse(fullText);
@@ -86,17 +93,44 @@ export class PsycheClaudeSDK {
     opts;
     lastInputResult = null;
     lastThrongletsExports = [];
+    lastRuntimeContext = {};
     constructor(engine, opts) {
         this.engine = engine;
         const state = engine.getState();
+        const context = opts?.context;
         this.opts = {
-            userId: opts?.userId ?? "default",
+            userId: resolveRelationshipUserId(opts?.userId ?? context?.userId),
             thronglets: opts?.thronglets ?? false,
-            agentId: opts?.agentId ?? state.meta.agentName ?? "psyche",
-            sessionId: opts?.sessionId ?? "claude-sdk",
+            agentId: opts?.agentId ?? context?.agentId,
+            sessionId: opts?.sessionId ?? context?.sessionId,
             locale: opts?.locale ?? "en",
+            ambient: opts?.ambient === true ? {} : (opts?.ambient || undefined),
         };
     }
+    async resolveAmbientPriors(userMessage) {
+        return resolveAmbientPriorsForTurn(userMessage, {
+            enabled: Boolean(this.opts.ambient),
+            thronglets: this.opts.ambient
+                ? {
+                    ...this.opts.ambient,
+                    space: this.opts.ambient.space ?? "psyche",
+                }
+                : undefined,
+        });
+    }
+    resolveAgentId(runtime) {
+        return this.opts.agentId
+            ?? runtime?.agentId
+            ?? this.lastRuntimeContext.agentId
+            ?? this.engine.getState().meta.agentName
+            ?? "psyche";
+    }
+    resolveSessionId(runtime) {
+        return this.opts.sessionId
+            ?? runtime?.sessionId
+            ?? this.lastRuntimeContext.sessionId
+            ?? "claude-sdk";
+    }
     // ── Protocol (stable, cacheable) ──────────────────────────
     /**
      * Returns the stable emotional protocol prompt.
@@ -119,9 +153,23 @@ export class PsycheClaudeSDK {
                 {
                     hooks: [
                         async (input) => {
+                            const runtimeContext = {
+                                agentId: typeof input.agent_id === "string" && input.agent_id.trim()
+                                    ? input.agent_id
+                                    : undefined,
+                                sessionId: typeof input.session_id === "string" && input.session_id.trim()
+                                    ? input.session_id
+                                    : undefined,
+                            };
+                            self.lastRuntimeContext = {
+                                agentId: runtimeContext.agentId ?? self.lastRuntimeContext.agentId,
+                                sessionId: runtimeContext.sessionId ?? self.lastRuntimeContext.sessionId,
+                            };
                             const userMessage = input.user_message ?? "";
+                            const ambientPriors = await self.resolveAmbientPriors(userMessage);
                             const result = await self.engine.processInput(userMessage, {
                                 userId: self.opts.userId,
+                                ambientPriors,
                             });
                             self.lastInputResult = result;
                             // Cache Thronglets exports from this turn
@@ -163,11 +211,13 @@ export class PsycheClaudeSDK {
     getThrongletsTraces() {
         if (!this.opts.thronglets)
             return [];
+        const agentId = this.resolveAgentId();
+        const sessionId = this.resolveSessionId();
         return this.lastThrongletsExports.map((exp) => ({
             ...serializeThrongletsExportAsTrace(exp, {
-                sessionId: this.opts.sessionId,
+                sessionId,
             }),
-            agent_id: this.opts.agentId,
+            agent_id: agentId,
         }));
     }
     /**
@@ -185,7 +235,7 @@ export class PsycheClaudeSDK {
         const s = state.current;
         return {
             kind: "psyche_state",
-            agent_id: this.opts.agentId,
+            agent_id: this.resolveAgentId(),
             message: `order:${s.order} flow:${s.flow} boundary:${s.boundary} resonance:${s.resonance}`,
         };
     }
@@ -210,7 +260,7 @@ export class PsycheClaudeSDK {
         const locale = this.opts.locale;
         const emotionDesc = describeEmotionalState(s, locale);
         const highlights = describeDimensionHighlights(s, locale);
-        return `[${this.opts.agentId}] ${emotionDesc}${highlights ? " — " + highlights : ""}`;
+        return `[${this.resolveAgentId()}] ${emotionDesc}${highlights ? " — " + highlights : ""}`;
     }
     /**
      * Get raw Thronglets exports from the most recent turn.

package/dist/adapters/http.js

@@ -7,7 +7,7 @@
 //   const server = createPsycheServer(engine, { port: 3210 });
 //
 // Endpoints:
-//   POST /process-input  { text, userId? }  → { systemContext, dynamicContext, stimulus, replyEnvelope?, ...compat aliases, sessionBridge?, writebackFeedback?, externalContinuity?, throngletsExports?, policyContext }
+//   POST /process-input  { text, userId?, ambientPriors? }  → { systemContext, dynamicContext, ambientPriors?, ambientPriorContext?, appraisal, legacyStimulus, stimulus, replyEnvelope?, ...compat aliases, sessionBridge?, writebackFeedback?, externalContinuity?, throngletsExports?, policyContext }
 //   POST /process-output { text, userId?, signals?, signalConfidence? }  → { cleanedText, stateChanged }
 //   GET  /state                             → PsycheState + overlay
 //   GET  /overlay                           → PsycheOverlay (arousal/valence/agency/vulnerability)
@@ -16,6 +16,7 @@
 // Zero dependencies — uses node:http only.
 // ============================================================
 import { createServer } from "node:http";
+import { parseAmbientPriorsInput } from "../ambient-runtime.js";
 import { computeOverlay } from "../overlay.js";
 const VALID_WRITEBACK_SIGNALS = new Set([
     "trust_up",
@@ -35,6 +36,9 @@ function parseSignals(value) {
     const parsed = value.filter((item) => (typeof item === "string" && VALID_WRITEBACK_SIGNALS.has(item)));
     return parsed.length > 0 ? [...new Set(parsed)] : undefined;
 }
+function parseAmbientPriors(value) {
+    return parseAmbientPriorsInput(value);
+}
 // ── Server ───────────────────────────────────────────────────
 /**
  * Create an HTTP server that exposes PsycheEngine via REST API.
@@ -89,8 +93,30 @@ export function createPsycheServer(engine, opts) {
             // POST /process-input
             if (req.method === "POST" && url.pathname === "/process-input") {
                 const body = await readBody(req);
-                const result = await engine.processInput(body.text ?? "", { userId: body.userId });
-                json(res, 200, result);
+                const result = await engine.processInput(body.text ?? "", {
+                    userId: body.userId,
+                    ambientPriors: parseAmbientPriors(body.ambientPriors),
+                });
+                json(res, 200, {
+                    systemContext: result.systemContext,
+                    dynamicContext: result.dynamicContext,
+                    ambientPriors: result.ambientPriors ?? [],
+                    ambientPriorContext: result.ambientPriorContext ?? null,
+                    appraisal: result.appraisal,
+                    legacyStimulus: result.legacyStimulus,
+                    stimulus: result.stimulus,
+                    replyEnvelope: result.replyEnvelope ?? null,
+                    policyModifiers: result.policyModifiers ?? null,
+                    subjectivityKernel: result.subjectivityKernel ?? null,
+                    responseContract: result.responseContract ?? null,
+                    generationControls: result.generationControls ?? null,
+                    sessionBridge: result.sessionBridge ?? null,
+                    writebackFeedback: result.writebackFeedback ?? null,
+                    externalContinuity: result.externalContinuity ?? null,
+                    throngletsExports: result.throngletsExports ?? null,
+                    policyContext: result.policyContext,
+                    observability: result.observability ?? null,
+                });
                 return;
             }
             // POST /process-output

package/dist/adapters/langchain.d.ts

@@ -1,4 +1,8 @@
 import type { PsycheEngine } from "../core.js";
+import { type ThrongletsAmbientRuntimeOptions } from "../ambient-runtime.js";
+export interface PsycheLangChainOptions {
+    ambient?: boolean | ThrongletsAmbientRuntimeOptions;
+}
 /**
  * LangChain integration helper for PsycheEngine.
  *
@@ -27,9 +31,11 @@ import type { PsycheEngine } from "../core.js";
  */
 export declare class PsycheLangChain {
     private readonly engine;
-    constructor(engine: PsycheEngine);
+    private readonly opts;
+    constructor(engine: PsycheEngine, opts?: PsycheLangChainOptions);
     private readonly validSignals;
     private parseSignals;
+    private resolveAmbientPriors;
     /**
      * Get the system message to inject into the LLM call.
      * Combines the protocol (cacheable) and dynamic context (per-turn).

package/dist/adapters/langchain.js

@@ -12,6 +12,7 @@
 // It provides the hooks you need to wire psyche into any
 // LangChain pipeline without requiring langchain as a dependency.
 // ============================================================
+import { resolveAmbientPriorsForTurn, } from "../ambient-runtime.js";
 /**
  * LangChain integration helper for PsycheEngine.
  *
@@ -40,8 +41,10 @@
  */
 export class PsycheLangChain {
     engine;
-    constructor(engine) {
+    opts;
+    constructor(engine, opts = {}) {
         this.engine = engine;
+        this.opts = opts;
     }
     validSignals = new Set([
         "trust_up",
@@ -61,6 +64,18 @@ export class PsycheLangChain {
         const parsed = signals.filter((signal) => this.validSignals.has(signal));
         return parsed.length > 0 ? [...new Set(parsed)] : undefined;
     }
+    async resolveAmbientPriors(userText) {
+        const ambient = this.opts.ambient;
+        return resolveAmbientPriorsForTurn(userText, {
+            enabled: Boolean(ambient),
+            thronglets: ambient
+                ? {
+                    ...(ambient === true ? {} : ambient),
+                    space: ambient === true ? "psyche" : (ambient.space ?? "psyche"),
+                }
+                : undefined,
+        });
+    }
     /**
      * Get the system message to inject into the LLM call.
      * Combines the protocol (cacheable) and dynamic context (per-turn).
@@ -68,7 +83,10 @@ export class PsycheLangChain {
      * Call this BEFORE the LLM invocation.
      */
     async getSystemMessage(userText, opts) {
-        const result = await this.engine.processInput(userText, opts);
+        const result = await this.engine.processInput(userText, {
+            ...opts,
+            ambientPriors: await this.resolveAmbientPriors(userText),
+        });
         return result.systemContext + "\n\n" + result.dynamicContext;
     }
     /**
@@ -78,7 +96,10 @@ export class PsycheLangChain {
      * instead of re-parsing prompt prose.
      */
     async prepareInvocation(userText, opts) {
-        const result = await this.engine.processInput(userText, opts);
+        const result = await this.engine.processInput(userText, {
+            ...opts,
+            ambientPriors: await this.resolveAmbientPriors(userText),
+        });
         const generationControls = result.replyEnvelope?.generationControls ?? result.generationControls;
         const controls = {
             ...(generationControls ?? {}),

package/dist/adapters/mcp-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/adapters/mcp-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runMcpServer } from "./mcp.js";
+runMcpServer().catch((err) => {
+    process.stderr.write(`psyche-mcp fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/adapters/mcp.d.ts

@@ -1,6 +1,14 @@
-#!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PsycheEngine } from "../core.js";
+import { fetchAmbientPriorsFromThronglets, type ThrongletsAmbientRuntimeOptions } from "../ambient-runtime.js";
+import type { AmbientPriorView } from "../types.js";
+export interface McpAmbientRuntimeOptions {
+    mode?: "auto" | "off";
+    thronglets?: ThrongletsAmbientRuntimeOptions;
+    fetcher?: typeof fetchAmbientPriorsFromThronglets;
+}
 declare function getEngine(): Promise<PsycheEngine>;
+export declare function resolveRuntimeAmbientPriors(text: string, explicit?: AmbientPriorView[], opts?: McpAmbientRuntimeOptions): Promise<AmbientPriorView[] | undefined>;
 declare const server: McpServer;
+export declare function runMcpServer(): Promise<void>;
 export { server, getEngine };