psyche-ai 10.0.4 → 10.1.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-1316%20passing-brightgreen)]()
+[![tests](https://img.shields.io/badge/tests-1405%20passing-brightgreen)]()
 [![deps](https://img.shields.io/badge/dependencies-0-blue)]()
 [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
 
@@ -446,19 +446,25 @@ const engine = new PsycheEngine({
 
 ## 不只是 OpenClaw
 
-Psyche 是通用的，任何 AI 框架都能用：
+Psyche 是通用的，6 个 adapter 覆盖主流 agent 框架：
 
 ```bash
 npm install psyche-ai
 ```
 
 ```javascript
+// Claude Agent SDK
+import { PsycheClaudeSDK } from "psyche-ai/claude-sdk";
+
 // Vercel AI SDK
 import { psycheMiddleware } from "psyche-ai/vercel-ai";
 
 // LangChain
 import { PsycheLangChain } from "psyche-ai/langchain";
 
+// MCP（Claude Desktop / Cursor / Windsurf / Claude Code）
+// npx psyche-mcp --mbti ENFP --name Luna
+
 // 任何语言（HTTP API）
 // psyche serve --port 3210
 ```

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

@@ -0,0 +1,144 @@
+import type { PsycheEngine, ProcessInputResult } from "../core.js";
+import type { ThrongletsExport, ThrongletsTracePayload, WritebackSignalType } from "../types.js";
+interface HookInput {
+    session_id: string;
+    cwd: string;
+    hook_event_name: string;
+    agent_id?: string;
+    agent_type?: string;
+    [key: string]: unknown;
+}
+interface HookOutput {
+    systemMessage?: string;
+    continue?: boolean;
+}
+type HookCallback = (input: HookInput, toolUseID: string | undefined, context: {
+    signal: AbortSignal;
+}) => Promise<HookOutput | undefined>;
+interface HookCallbackMatcher {
+    matcher?: string;
+    hooks: HookCallback[];
+    timeout?: number;
+}
+type HookEvent = string;
+type HooksConfig = Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+interface SystemPromptPreset {
+    type: "preset";
+    preset: string;
+    append?: string;
+}
+interface AgentOptions {
+    systemPrompt?: string | SystemPromptPreset;
+    hooks?: HooksConfig;
+    [key: string]: unknown;
+}
+declare function stripPsycheTags(text: string): string;
+/** Signal payload for `mcp__thronglets__signal_post` */
+export interface ThrongletsSignalPayload {
+    kind: "psyche_state";
+    agent_id: string;
+    message: string;
+}
+export interface PsycheClaudeSdkOptions {
+    /** User ID for multi-user relationship tracking. Default: "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" */
+    agentId?: string;
+    /** Session ID for Thronglets trace serialization */
+    sessionId?: string;
+    /** Override locale for protocol context */
+    locale?: "zh" | "en";
+}
+/**
+ * Psyche integration for the Claude Agent SDK.
+ *
+ * Provides hook-based emotional context injection (automatic via
+ * UserPromptSubmit) and explicit output processing (processResponse).
+ *
+ * @example
+ * ```ts
+ * const psyche = new PsycheClaudeSDK(engine);
+ * const options = psyche.mergeOptions({ model: "sonnet" });
+ * for await (const msg of query({ prompt: "Hey!", options })) { ... }
+ * await psyche.processResponse(fullText);
+ * ```
+ */
+export declare class PsycheClaudeSDK {
+    private engine;
+    private opts;
+    private lastInputResult;
+    private lastThrongletsExports;
+    constructor(engine: PsycheEngine, opts?: PsycheClaudeSdkOptions);
+    /**
+     * Returns the stable emotional protocol prompt.
+     * Suitable for `systemPrompt.append` — changes only when locale changes.
+     */
+    getProtocol(): string;
+    /**
+     * Returns Claude Agent SDK hooks config.
+     *
+     * - `UserPromptSubmit`: calls `engine.processInput()`, injects
+     *   `dynamicContext` as `systemMessage` visible to the model.
+     */
+    getHooks(): HooksConfig;
+    /**
+     * Process the assistant's full output text.
+     *
+     * Strips `<psyche_update>` tags and updates internal chemistry.
+     * Call this after consuming the full query output.
+     *
+     * @returns Cleaned text with tags removed
+     */
+    processResponse(text: string, opts?: {
+        signals?: WritebackSignalType[];
+        signalConfidence?: number;
+    }): Promise<string>;
+    /**
+     * Get Thronglets trace payloads from the most recent turn.
+     *
+     * Returns serialized traces ready for `mcp__thronglets__trace_record`.
+     * Each trace includes `agent_id` for multi-agent disambiguation.
+     * Empty array if thronglets option is disabled or no exports were produced.
+     */
+    getThrongletsTraces(): (ThrongletsTracePayload & {
+        agent_id: string;
+    })[];
+    /**
+     * Get a signal payload for `mcp__thronglets__signal_post`.
+     *
+     * Broadcasts current chemical state so other agents can sense this
+     * agent's emotional state via `substrate_query(intent: "signals", kind: "psyche_state")`.
+     *
+     * Returns null if thronglets is disabled or no processInput has run yet.
+     */
+    getThrongletsSignal(): ThrongletsSignalPayload | null;
+    /**
+     * Get raw Thronglets exports from the most recent turn.
+     */
+    getThrongletsExports(): ThrongletsExport[];
+    /**
+     * Get the last processInput result (useful for inspecting
+     * stimulus, subjectivityKernel, generationControls, etc.)
+     */
+    getLastInputResult(): ProcessInputResult | null;
+    /**
+     * Merge Psyche hooks and system prompt into existing options.
+     *
+     * This is the primary integration point — pass the result to `query()`.
+     *
+     * @example
+     * ```ts
+     * const options = psyche.mergeOptions({ model: "sonnet", allowedTools: ["Read"] });
+     * for await (const msg of query({ prompt: "Hey!", options })) { ... }
+     * ```
+     */
+    mergeOptions(baseOptions?: AgentOptions): AgentOptions;
+}
+/**
+ * Strip `<psyche_update>` tags from a text string.
+ *
+ * Useful for post-processing query output when not using `processResponse`.
+ */
+export { stripPsycheTags };

package/dist/adapters/claude-sdk.js

@@ -0,0 +1,229 @@
+// ============================================================
+// Claude Agent SDK Adapter — Hook-based integration
+//
+// Usage:
+//   import { PsycheEngine, MemoryStorageAdapter } from "psyche-ai";
+//   import { PsycheClaudeSDK } from "psyche-ai/claude-sdk";
+//   import { query } from "@anthropic-ai/claude-agent-sdk";
+//
+//   const engine = new PsycheEngine({ name: "Luna", mbti: "ENFP" }, new MemoryStorageAdapter());
+//   await engine.initialize();
+//
+//   const psyche = new PsycheClaudeSDK(engine);
+//   let text = "";
+//   for await (const msg of query({ prompt: "Hey!", options: psyche.mergeOptions() })) {
+//     text += msg.content ?? "";
+//   }
+//   const clean = await psyche.processResponse(text);
+//
+// Architecture:
+//   - UserPromptSubmit hook → processInput → inject dynamicContext via systemMessage
+//   - systemPrompt.append → stable protocol context (cached, amortized)
+//   - processResponse() → strip <psyche_update> tags + update chemistry
+//   - Thronglets traces → optional export after each turn
+//
+// The SDK has no middleware interface and hooks cannot modify assistant
+// output, so processResponse must be called explicitly by the host.
+// ============================================================
+import { serializeThrongletsExportAsTrace } from "../thronglets-runtime.js";
+// ── Tag stripping ────────────────────────────────────────────
+const PSYCHE_TAG_RE = /<psyche_update>[\s\S]*?<\/psyche_update>/g;
+function stripPsycheTags(text) {
+    return text.replace(PSYCHE_TAG_RE, "").trim();
+}
+// ── Main class ──────────────────────────────────────────────
+/**
+ * Psyche integration for the Claude Agent SDK.
+ *
+ * Provides hook-based emotional context injection (automatic via
+ * UserPromptSubmit) and explicit output processing (processResponse).
+ *
+ * @example
+ * ```ts
+ * const psyche = new PsycheClaudeSDK(engine);
+ * const options = psyche.mergeOptions({ model: "sonnet" });
+ * for await (const msg of query({ prompt: "Hey!", options })) { ... }
+ * await psyche.processResponse(fullText);
+ * ```
+ */
+export class PsycheClaudeSDK {
+    engine;
+    opts;
+    lastInputResult = null;
+    lastThrongletsExports = [];
+    constructor(engine, opts) {
+        this.engine = engine;
+        const state = engine.getState();
+        this.opts = {
+            userId: opts?.userId ?? "default",
+            thronglets: opts?.thronglets ?? false,
+            agentId: opts?.agentId ?? state.meta.agentName ?? "psyche",
+            sessionId: opts?.sessionId ?? "claude-sdk",
+            locale: opts?.locale ?? "en",
+        };
+    }
+    // ── Protocol (stable, cacheable) ──────────────────────────
+    /**
+     * Returns the stable emotional protocol prompt.
+     * Suitable for `systemPrompt.append` — changes only when locale changes.
+     */
+    getProtocol() {
+        return this.engine.getProtocol(this.opts.locale);
+    }
+    // ── Hooks ─────────────────────────────────────────────────
+    /**
+     * Returns Claude Agent SDK hooks config.
+     *
+     * - `UserPromptSubmit`: calls `engine.processInput()`, injects
+     *   `dynamicContext` as `systemMessage` visible to the model.
+     */
+    getHooks() {
+        const self = this;
+        return {
+            UserPromptSubmit: [
+                {
+                    hooks: [
+                        async (input) => {
+                            const userMessage = input.user_message ?? "";
+                            const result = await self.engine.processInput(userMessage, {
+                                userId: self.opts.userId,
+                            });
+                            self.lastInputResult = result;
+                            // Cache Thronglets exports from this turn
+                            if (self.opts.thronglets && result.throngletsExports) {
+                                self.lastThrongletsExports = result.throngletsExports;
+                            }
+                            return { systemMessage: result.dynamicContext };
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    // ── Output processing ─────────────────────────────────────
+    /**
+     * Process the assistant's full output text.
+     *
+     * Strips `<psyche_update>` tags and updates internal chemistry.
+     * Call this after consuming the full query output.
+     *
+     * @returns Cleaned text with tags removed
+     */
+    async processResponse(text, opts) {
+        const result = await this.engine.processOutput(text, {
+            userId: this.opts.userId,
+            signals: opts?.signals,
+            signalConfidence: opts?.signalConfidence,
+        });
+        return result.cleanedText;
+    }
+    // ── Thronglets integration ────────────────────────────────
+    /**
+     * Get Thronglets trace payloads from the most recent turn.
+     *
+     * Returns serialized traces ready for `mcp__thronglets__trace_record`.
+     * Each trace includes `agent_id` for multi-agent disambiguation.
+     * Empty array if thronglets option is disabled or no exports were produced.
+     */
+    getThrongletsTraces() {
+        if (!this.opts.thronglets)
+            return [];
+        return this.lastThrongletsExports.map((exp) => ({
+            ...serializeThrongletsExportAsTrace(exp, {
+                sessionId: this.opts.sessionId,
+            }),
+            agent_id: this.opts.agentId,
+        }));
+    }
+    /**
+     * Get a signal payload for `mcp__thronglets__signal_post`.
+     *
+     * Broadcasts current chemical state so other agents can sense this
+     * agent's emotional state via `substrate_query(intent: "signals", kind: "psyche_state")`.
+     *
+     * Returns null if thronglets is disabled or no processInput has run yet.
+     */
+    getThrongletsSignal() {
+        if (!this.opts.thronglets)
+            return null;
+        const state = this.engine.getState();
+        const c = state.current;
+        return {
+            kind: "psyche_state",
+            agent_id: this.opts.agentId,
+            message: `DA:${c.DA} HT:${c.HT} CORT:${c.CORT} OT:${c.OT} NE:${c.NE} END:${c.END}`,
+        };
+    }
+    /**
+     * Get raw Thronglets exports from the most recent turn.
+     */
+    getThrongletsExports() {
+        if (!this.opts.thronglets)
+            return [];
+        return [...this.lastThrongletsExports];
+    }
+    // ── State access ──────────────────────────────────────────
+    /**
+     * Get the last processInput result (useful for inspecting
+     * stimulus, subjectivityKernel, generationControls, etc.)
+     */
+    getLastInputResult() {
+        return this.lastInputResult;
+    }
+    // ── Convenience ───────────────────────────────────────────
+    /**
+     * Merge Psyche hooks and system prompt into existing options.
+     *
+     * This is the primary integration point — pass the result to `query()`.
+     *
+     * @example
+     * ```ts
+     * const options = psyche.mergeOptions({ model: "sonnet", allowedTools: ["Read"] });
+     * for await (const msg of query({ prompt: "Hey!", options })) { ... }
+     * ```
+     */
+    mergeOptions(baseOptions) {
+        const protocol = this.getProtocol();
+        const hooks = this.getHooks();
+        // Merge system prompt
+        let systemPrompt;
+        const base = baseOptions?.systemPrompt;
+        if (typeof base === "object" && base !== null && "type" in base) {
+            // Preset mode — append protocol
+            systemPrompt = {
+                ...base,
+                append: protocol + (base.append ? "\n\n" + base.append : ""),
+            };
+        }
+        else if (typeof base === "string") {
+            // String mode — prepend protocol
+            systemPrompt = protocol + "\n\n" + base;
+        }
+        else {
+            // No base — use preset with append
+            systemPrompt = {
+                type: "preset",
+                preset: "claude_code",
+                append: protocol,
+            };
+        }
+        // Merge hooks (preserve existing hooks, add Psyche hooks)
+        const mergedHooks = { ...(baseOptions?.hooks ?? {}) };
+        for (const [event, matchers] of Object.entries(hooks)) {
+            const existing = mergedHooks[event] ?? [];
+            mergedHooks[event] = [...existing, ...matchers];
+        }
+        return {
+            ...baseOptions,
+            systemPrompt,
+            hooks: mergedHooks,
+        };
+    }
+}
+// ── Utility: strip tags from message stream ─────────────────
+/**
+ * Strip `<psyche_update>` tags from a text string.
+ *
+ * Useful for post-processing query output when not using `processResponse`.
+ */
+export { stripPsycheTags };

package/dist/index.js

@@ -7,10 +7,11 @@
 // and advanced use, but are NOT part of the public contract.
 //
 // Framework adapters available via subpath imports:
-//   psyche-ai/openclaw   — OpenClaw plugin
-//   psyche-ai/vercel-ai  — Vercel AI SDK middleware
-//   psyche-ai/langchain  — LangChain helper
-//   psyche-ai/http       — HTTP server for Python/Go/etc.
+//   psyche-ai/openclaw    — OpenClaw plugin
+//   psyche-ai/vercel-ai   — Vercel AI SDK middleware
+//   psyche-ai/langchain   — LangChain helper
+//   psyche-ai/http        — HTTP server for Python/Go/etc.
+//   psyche-ai/claude-sdk  — Claude Agent SDK hooks
 // ============================================================
 // ── Core engine ─────────────────────────────────────────────
 export { PsycheEngine } from "./core.js";

package/dist/prompt.js

@@ -516,16 +516,6 @@ function buildMirrorConstraints(userText, locale) {
     const title = locale === "zh" ? "镜像约束" : "Mirror Constraints";
     return `[${title}]\n${lines.join("\n")}`;
 }
-function buildCompactSensingContext(_userText, locale, algorithmStimulus) {
-    if (locale === "zh") {
-        return algorithmStimulus
-            ? `[情绪感知] 算法初判:${algorithmStimulus}；你终判。`
-            : `[情绪感知] 情绪由你终判。`;
-    }
-    return algorithmStimulus
-        ? `[Emotional Sensing] Algorithm hint: ${algorithmStimulus}; final tonal read is yours.`
-        : `[Emotional Sensing] Make the final tonal read yourself.`;
-}
 function isNeutralMetacognitiveNote(note) {
     return note.includes("normal parameters")
         || note.includes("No regulation needed")
@@ -936,11 +926,14 @@ export function buildCompactContext(state, userId, opts) {
             parts.push(bias);
     }
     // ── 5. Sensing ──
-    if (userText) {
-        if (opts?.responseContractContext) {
-            parts.push(buildCompactSensingContext(userText, locale, algoStimulus));
-        }
-        else if (locale === "zh") {
+    // v10.1: When SubjectivityKernel + ResponseContract are present (engine path),
+    // sensing is redundant — the kernel already encodes the *consequence* of the
+    // stimulus (pressure, warmth, boundary state). "你终判" is misleading because
+    // the kernel has already been computed. ambiguityPlane handles real uncertainty.
+    //
+    // Legacy verbose path (no ResponseContract) kept for non-engine callers.
+    if (userText && !opts?.responseContractContext) {
+        if (locale === "zh") {
             parts.push(`[情绪感知]\n` +
                 `对方刚才说了: "${userText.slice(0, 200)}"\n` +
                 (algoStimulus ? `算法初判: ${algoStimulus}（仅供参考，你来终判）\n` : "") +

package/llms.txt

@@ -112,6 +112,24 @@ const output = await engine.processOutput(llmResponse);
 }
 ```
 
+## Quick Start (Claude Agent SDK)
+
+```ts
+import { PsycheEngine, MemoryStorageAdapter } from "psyche-ai";
+import { PsycheClaudeSDK } from "psyche-ai/claude-sdk";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+const engine = new PsycheEngine({ name: "Luna" }, new MemoryStorageAdapter());
+await engine.initialize();
+
+const psyche = new PsycheClaudeSDK(engine);
+let text = "";
+for await (const msg of query({ prompt: "Hey!", options: psyche.mergeOptions() })) {
+  text += msg.content ?? "";
+}
+await psyche.processResponse(text);
+```
+
 ## Why Hosts Use It
 
 - zero extra model calls
@@ -147,6 +165,7 @@ npx psyche-mcp
 ## Adapter Sub-paths
 
 - `psyche-ai` — core engine (PsycheEngine, MemoryStorageAdapter)
+- `psyche-ai/claude-sdk` — Claude Agent SDK hooks (PsycheClaudeSDK)
 - `psyche-ai/mcp` — MCP stdio server
 - `psyche-ai/vercel-ai` — Vercel AI SDK middleware
 - `psyche-ai/langchain` — LangChain adapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "psyche-ai",
-  "version": "10.0.4",
+  "version": "10.1.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",
@@ -30,6 +30,10 @@
     "./mcp": {
       "types": "./dist/adapters/mcp.d.ts",
       "default": "./dist/adapters/mcp.js"
+    },
+    "./claude-sdk": {
+      "types": "./dist/adapters/claude-sdk.d.ts",
+      "default": "./dist/adapters/claude-sdk.js"
     }
   },
   "bin": {