psyche-ai 9.2.6 → 9.2.8

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-1291%20passing-brightgreen)]()
+[![tests](https://img.shields.io/badge/tests-1307%20passing-brightgreen)]()
 [![deps](https://img.shields.io/badge/dependencies-0-blue)]()
 [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
 
@@ -23,6 +23,91 @@ Psyche 不是给模型贴一层“情绪 UI”。
 - **源码仓库**: [`oasyce_psyche`](https://github.com/Shangri-la-0428/oasyce_psyche)
 - **官网**: [psyche.oasyce.com](https://psyche.oasyce.com)
 
+## 第一性原理
+
+Psyche 要解决的不可压缩问题只有一个：
+
+**互动历史必须持续改变 agent 后续的行为分布，而且这件事要足够便宜、足够稳定、足够可移植。**
+
+因此它的本体不是：
+
+- 情绪标签系统
+- 陪伴产品
+- prompt 皮肤
+- 记忆仓库
+
+它真正是：
+
+- 本地主观性内核
+- 关系动力学运行时
+- 宿主可消费的行为控制面
+
+更完整的战略定义见：
+
+- [docs/PROJECT_DIRECTION.md](docs/PROJECT_DIRECTION.md)
+- [docs/STACK_ARCHITECTURE.md](docs/STACK_ARCHITECTURE.md)
+
+## 冻结身份蓝图
+
+跨 Psyche / Thronglets / Oasyce Net / Oasyce Chain 的身份抽象现在冻结成 4 个对象：
+
+1. `principal`：持续主体
+2. `account`：资产与结算容器
+3. `delegate`：被授权执行者
+4. `session`：一次具体运行，永不作为经济主体
+
+对应的四层分工是：
+
+- `Psyche = subjective continuity substrate`
+- `Thronglets = delegate continuity + session traces/coordination + emergent collective intelligence`
+- `Oasyce Net = policy, operations, and resource orchestration`
+- `Oasyce Chain = account truth, authorization truth, commitments, settlement, and public finality`
+
+正式版本见：
+
+- [docs/IDENTITY_MODEL.md](docs/IDENTITY_MODEL.md)
+- [docs/STACK_ARCHITECTURE.md](docs/STACK_ARCHITECTURE.md)
+
+## Psyche 和 Thronglets 的关系
+
+两者不是竞争关系，也不该揉成一个系统。
+
+- **Psyche** 负责私有主观性：关系残留、未完成张力、行为偏置、局部学习
+- **Thronglets** 负责外部连续性：owner / device identity、签名、跨设备延续、低频可验证轨迹
+
+一句话：
+
+- `Psyche` 回答“我因此变成了什么”
+- `Thronglets` 回答“这个变化属于谁、谁能验证、谁能继续承认它”
+
+## 可分离安装
+
+这两层默认就是可分离的，不应互相成为硬依赖。
+
+- **只装 Psyche**：正常可用，拥有主观连续性和关系动力学；只是没有外部连续性层
+- **只装 Thronglets**：正常可用，拥有 delegate / session 连续性与环境协作；只是没有主观连续性内核
+- **两者都装**：Psyche 通过可选 `externalContinuity` envelope 输出稀疏、低频、可归属的 `signals / traces` 给 Thronglets
+
+原则上：
+
+- `Psyche` 必须 standalone 可用
+- `Thronglets` 必须 additive，而不是 Psyche 的运行前提
+- 两者之间只通过稀疏 `signal / trace` 接口连接
+
+更细的分层、边界和运行流见：[docs/STACK_ARCHITECTURE.md](docs/STACK_ARCHITECTURE.md)
+
+## 新概念准入规则
+
+以后引入任何新概念，先尝试压进这 5 个原始容器：
+
+1. `Relation Move`
+2. `Dyadic Field`
+3. `Open Loop / Residue`
+4. `Reply Bias / Control ABI`
+5. `Writeback / Learning`
+
+如果一个新概念放不进这 5 个盒子，先怀疑概念本身，而不是继续加对象类型。
+
 ## 为什么它值得被看见
 
 - **不是 persona prompt**：输入会留下持续主体偏置，不是一轮一清。
@@ -215,6 +300,8 @@ Psyche 现在更准确的目标，不是“模仿某种像人的风格”，而
 
 这样做不是为了加抽象层，而是为了减少散装编排，让宿主稳定消费同一套行为 ABI。
 
+当前主线里，`processInput()` 会直接返回 `replyEnvelope` 作为规范主接口；原有平级字段继续保留为兼容别名，避免打断现有宿主。`policyModifiers` 不再属于规范主接口，只保留为 legacy raw vector。
+
 ### 内在世界
 
 Psyche 给 AI 一个始终运转的内在自我——不是条件触发，而是每时每刻都在：
@@ -436,7 +523,7 @@ Psyche 核心引擎永久开源（MIT）。
 ```bash
 npm install
 npm run build
-npm test           # 1291 tests
+npm test           # 1307 tests
 npm run typecheck  # strict mode
 ```
 

package/dist/adapters/http.js

@@ -7,14 +7,32 @@
 //   const server = createPsycheServer(engine, { port: 3210 });
 //
 // Endpoints:
-//   POST /process-input  { text, userId? }  → { systemContext, dynamicContext, stimulus, policyModifiers?, subjectivityKernel?, responseContract?, generationControls?, policyContext }
-//   POST /process-output { text, userId? }  → { cleanedText, stateChanged }
+//   POST /process-input  { text, userId? }  → { systemContext, dynamicContext, stimulus, replyEnvelope?, ...compat aliases, sessionBridge?, writebackFeedback?, externalContinuity?, throngletsExports?, policyContext }
+//   POST /process-output { text, userId?, signals?, signalConfidence? }  → { cleanedText, stateChanged }
 //   GET  /state                             → PsycheState
 //   GET  /protocol?locale=zh                → { protocol }
 //
 // Zero dependencies — uses node:http only.
 // ============================================================
 import { createServer } from "node:http";
+const VALID_WRITEBACK_SIGNALS = new Set([
+    "trust_up",
+    "trust_down",
+    "boundary_set",
+    "boundary_soften",
+    "repair_attempt",
+    "repair_landed",
+    "closeness_invite",
+    "withdrawal_mark",
+    "self_assertion",
+    "task_recenter",
+]);
+function parseSignals(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const parsed = value.filter((item) => (typeof item === "string" && VALID_WRITEBACK_SIGNALS.has(item)));
+    return parsed.length > 0 ? [...new Set(parsed)] : undefined;
+}
 // ── Server ───────────────────────────────────────────────────
 /**
  * Create an HTTP server that exposes PsycheEngine via REST API.
@@ -69,7 +87,11 @@ export function createPsycheServer(engine, opts) {
             // POST /process-output
             if (req.method === "POST" && url.pathname === "/process-output") {
                 const body = await readBody(req);
-                const result = await engine.processOutput(body.text ?? "", { userId: body.userId });
+                const result = await engine.processOutput(body.text ?? "", {
+                    userId: body.userId,
+                    signals: parseSignals(body.signals),
+                    signalConfidence: typeof body.signalConfidence === "number" ? body.signalConfidence : undefined,
+                });
                 json(res, 200, result);
                 return;
             }

package/dist/adapters/langchain.d.ts

@@ -28,6 +28,8 @@ import type { PsycheEngine } from "../core.js";
 export declare class PsycheLangChain {
     private readonly engine;
     constructor(engine: PsycheEngine);
+    private readonly validSignals;
+    private parseSignals;
     /**
      * Get the system message to inject into the LLM call.
      * Combines the protocol (cacheable) and dynamic context (per-turn).
@@ -59,5 +61,7 @@ export declare class PsycheLangChain {
      */
     processResponse(text: string, opts?: {
         userId?: string;
+        signals?: string[];
+        signalConfidence?: number;
     }): Promise<string>;
 }

package/dist/adapters/langchain.js

@@ -43,6 +43,24 @@ export class PsycheLangChain {
     constructor(engine) {
         this.engine = engine;
     }
+    validSignals = new Set([
+        "trust_up",
+        "trust_down",
+        "boundary_set",
+        "boundary_soften",
+        "repair_attempt",
+        "repair_landed",
+        "closeness_invite",
+        "withdrawal_mark",
+        "self_assertion",
+        "task_recenter",
+    ]);
+    parseSignals(signals) {
+        if (!signals)
+            return undefined;
+        const parsed = signals.filter((signal) => this.validSignals.has(signal));
+        return parsed.length > 0 ? [...new Set(parsed)] : undefined;
+    }
     /**
      * Get the system message to inject into the LLM call.
      * Combines the protocol (cacheable) and dynamic context (per-turn).
@@ -61,11 +79,12 @@ export class PsycheLangChain {
      */
     async prepareInvocation(userText, opts) {
         const result = await this.engine.processInput(userText, opts);
+        const generationControls = result.replyEnvelope?.generationControls ?? result.generationControls;
         const controls = {
-            ...(result.generationControls ?? {}),
-            maxTokens: result.generationControls?.maxTokens !== undefined && opts?.maxTokens !== undefined
-                ? Math.min(opts.maxTokens, result.generationControls.maxTokens)
-                : result.generationControls?.maxTokens ?? opts?.maxTokens,
+            ...(generationControls ?? {}),
+            maxTokens: generationControls?.maxTokens !== undefined && opts?.maxTokens !== undefined
+                ? Math.min(opts.maxTokens, generationControls.maxTokens)
+                : generationControls?.maxTokens ?? opts?.maxTokens,
         };
         return {
             systemMessage: result.systemContext + "\n\n" + result.dynamicContext,
@@ -80,7 +99,11 @@ export class PsycheLangChain {
      * Call this AFTER the LLM invocation, before showing output to the user.
      */
     async processResponse(text, opts) {
-        const result = await this.engine.processOutput(text, opts);
+        const result = await this.engine.processOutput(text, {
+            userId: opts?.userId,
+            signals: this.parseSignals(opts?.signals),
+            signalConfidence: opts?.signalConfidence,
+        });
         return result.cleanedText;
     }
 }

package/dist/adapters/mcp.js

@@ -145,8 +145,10 @@ server.resource("state", "psyche://state", {
 // ── Tools ──────────────────────────────────────────────────
 server.tool("process_input", "Process user input through the emotional engine. Returns emotional " +
     "context to inject into the LLM system prompt (systemContext + dynamicContext), " +
-    "detected stimulus type, behavioral policy modifiers, the narrow AI-first ABI " +
-    "(subjectivityKernel + responseContract), and generationControls. " +
+    "detected stimulus type, a canonical replyEnvelope, compatibility aliases " +
+    "(policyModifiers + subjectivityKernel + responseContract + generationControls), an optional " +
+    "externalContinuity envelope, and sparse low-frequency throngletsExports " +
+    "suitable for additive external continuity layers. " +
     "Call this BEFORE generating a response to the user.", {
     text: z.string().describe("The user's message text"),
     userId: z.string().optional().describe("Optional user ID for multi-user relationship tracking"),
@@ -160,10 +162,15 @@ server.tool("process_input", "Process user input through the emotional engine. R
                     systemContext: result.systemContext,
                     dynamicContext: result.dynamicContext,
                     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,
                 }, null, 2),
             }],
@@ -174,9 +181,11 @@ server.tool("process_output", "Process the LLM's response through the emotional
     "emotional contagion. Call this AFTER generating a response.", {
     text: z.string().describe("The LLM's response text"),
     userId: z.string().optional().describe("Optional user ID"),
-}, async ({ text, userId }) => {
+    signals: z.array(z.string()).optional().describe("Optional sparse writeback signals from the host"),
+    signalConfidence: z.number().min(0).max(1).optional().describe("Optional confidence for the supplied signals"),
+}, async ({ text, userId, signals, signalConfidence }) => {
     const eng = await getEngine();
-    const result = await eng.processOutput(text, { userId });
+    const result = await eng.processOutput(text, { userId, signals: signals, signalConfidence });
     return {
         content: [{
                 type: "text",

package/dist/adapters/openclaw.js

@@ -44,7 +44,7 @@ export function sanitizeOpenClawInputText(text) {
         .trim();
 }
 function getDominantAppraisalLabel(result) {
-    const appraisal = result.subjectivityKernel?.appraisal;
+    const appraisal = result.replyEnvelope?.subjectivityKernel?.appraisal ?? result.subjectivityKernel?.appraisal;
     if (!appraisal)
         return null;
     const entries = [
@@ -118,7 +118,7 @@ export function register(api) {
             }
             const engine = await getEngine(workspaceDir);
             const result = await engine.processInput(inputText, { userId: ctx.userId });
-            const controls = result.generationControls;
+            const controls = result.replyEnvelope?.generationControls ?? result.generationControls;
             const dominantAppraisal = getDominantAppraisalLabel(result);
             const state = engine.getState();
             logger.info(`Psyche [input] stimulus=${result.stimulus ?? "none"} | ` +

package/dist/adapters/vercel-ai.js

@@ -49,11 +49,13 @@ export function psycheMiddleware(engine, _opts) {
         transformParams: async ({ params }) => {
             const userText = extractLastUserText(params.prompt ?? []);
             const result = await engine.processInput(userText);
+            const envelope = result.replyEnvelope;
+            const generationControls = envelope?.generationControls ?? result.generationControls;
             const controls = {
-                ...(result.generationControls ?? {}),
-                maxTokens: result.generationControls?.maxTokens !== undefined && typeof params.maxTokens === "number"
-                    ? Math.min(params.maxTokens, result.generationControls.maxTokens)
-                    : result.generationControls?.maxTokens ?? (typeof params.maxTokens === "number" ? params.maxTokens : undefined),
+                ...(generationControls ?? {}),
+                maxTokens: generationControls?.maxTokens !== undefined && typeof params.maxTokens === "number"
+                    ? Math.min(params.maxTokens, generationControls.maxTokens)
+                    : generationControls?.maxTokens ?? (typeof params.maxTokens === "number" ? params.maxTokens : undefined),
             };
             const psycheContext = result.systemContext + "\n\n" + result.dynamicContext;
             return {

package/dist/core.d.ts

@@ -1,6 +1,7 @@
-import type { PsycheState, StimulusType, Locale, MBTIType, OutcomeScore, PsycheMode, PersonalityTraits, PolicyModifiers, ClassifierProvider, SubjectivityKernel, ResponseContract, GenerationControls } from "./types.js";
+import type { PsycheState, StimulusType, Locale, MBTIType, OutcomeScore, PsycheMode, PersonalityTraits, PolicyModifiers, ClassifierProvider, SubjectivityKernel, ResponseContract, GenerationControls, SessionBridgeState, ThrongletsExport, WritebackCalibrationFeedback, WritebackSignalType, ExternalContinuityEnvelope } from "./types.js";
 import type { StorageAdapter } from "./storage.js";
 import type { DiagnosticReport, SessionMetrics } from "./diagnostics.js";
+import type { ReplyEnvelope } from "./reply-envelope.js";
 export interface PsycheEngineConfig {
     mbti?: MBTIType;
     name?: string;
@@ -36,16 +37,28 @@ export interface ProcessInputResult {
     dynamicContext: string;
     /** Detected stimulus type from user input, null if none */
     stimulus: StimulusType | null;
-    /** v9: Structured behavioral policy modifiers — machine-readable "off baseline" signals */
+    /** Confidence of the primary algorithmic stimulus guess, if any */
+    stimulusConfidence?: number;
+    /** Legacy compatibility alias: raw policy vector behind the canonical replyEnvelope. */
     policyModifiers?: PolicyModifiers;
-    /** v9.3: Compact machine-readable subjective state for AI-first hosts */
+    /** v9.3+: canonical host-facing reply surface */
+    replyEnvelope?: ReplyEnvelope;
+    /** v9.3 compatibility alias: use replyEnvelope.subjectivityKernel when possible */
     subjectivityKernel?: SubjectivityKernel;
-    /** v9.3: Compact next-reply behavioral envelope */
+    /** v9.3 compatibility alias: use replyEnvelope.responseContract when possible */
     responseContract?: ResponseContract;
-    /** v9.3: Mechanical host controls derived from the reply envelope */
+    /** v9.3 compatibility alias: use replyEnvelope.generationControls when possible */
     generationControls?: GenerationControls;
+    /** v9.2.7: cold-start carry derived from persisted relation state */
+    sessionBridge?: SessionBridgeState | null;
+    /** v9.2.8: sparse writeback signals evaluated on the latest turn */
+    writebackFeedback?: WritebackCalibrationFeedback[];
+    /** v9.2.8: optional additive external continuity contract */
+    externalContinuity?: ExternalContinuityEnvelope<ThrongletsExport>;
+    /** v9.2.8: sparse low-frequency export surface suitable for Thronglets */
+    throngletsExports?: ThrongletsExport[];
     /**
-     * v9: Ready-to-use LLM prompt fragment summarizing current behavioral policy.
+     * Legacy compatibility alias: ready-to-use prompt fragment summarizing raw policy modifiers.
      *
      * This is the output of `buildPolicyContext(policyModifiers, locale)` —
      * a human-readable string like "[行为策略] 简短回复、被动应答为主".
@@ -65,6 +78,11 @@ export interface ProcessOutputResult {
     /** Whether chemistry was meaningfully updated (contagion or psyche_update) */
     stateChanged: boolean;
 }
+export interface ProcessOutputOptions {
+    userId?: string;
+    signals?: WritebackSignalType[];
+    signalConfidence?: number;
+}
 export interface ProcessOutcomeResult {
     /** Outcome evaluation score (-1 to 1) */
     outcomeScore: OutcomeScore;
@@ -89,6 +107,8 @@ export declare class PsycheEngine {
     private lastReport;
     /** URL for auto-submitting diagnostic reports */
     private readonly feedbackUrl;
+    /** Most recent algorithmic stimulus read + confidence band */
+    private lastStimulusAssessment;
     constructor(config: PsycheEngineConfig | undefined, storage: StorageAdapter);
     /**
      * Load or create initial state. Must be called before processInput/processOutput.
@@ -105,9 +125,7 @@ export declare class PsycheEngine {
      * Phase 2: Process LLM output text.
      * Parses <psyche_update> tags, applies contagion, strips tags.
      */
-    processOutput(text: string, opts?: {
-        userId?: string;
-    }): Promise<ProcessOutputResult>;
+    processOutput(text: string, opts?: ProcessOutputOptions): Promise<ProcessOutputResult>;
     /**
      * Phase 3 (optional): Explicitly evaluate the outcome of the last interaction.
      *