@xopcai/xopc 0.0.227 → 0.0.229

package/dist/packages/gateway-contract/src/turn-outcome.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+const TurnOutcomeDeliverableKindSchema = z.enum([
+	"document",
+	"spreadsheet",
+	"presentation",
+	"pdf",
+	"image",
+	"video",
+	"audio",
+	"site",
+	"archive",
+	"file"
+]);
+const TurnOutcomeArtifactLocationSchema = z.enum([
+	"workspace",
+	"external_host",
+	"worktree",
+	"remote_runtime",
+	"artifact_store"
+]);
+const TurnOutcomeArtifactAvailabilitySchema = z.enum([
+	"materializing",
+	"available",
+	"expired",
+	"missing",
+	"failed"
+]);
+const TurnOutcomeArtifactCapabilitySchema = z.enum([
+	"preview",
+	"download",
+	"open",
+	"import",
+	"share",
+	"regenerate"
+]);
+const TurnOutcomeDeliverableSchema = z.object({
+	artifactId: z.string().min(1),
+	title: z.string().min(1),
+	kind: TurnOutcomeDeliverableKindSchema,
+	mimeType: z.string().optional(),
+	sizeBytes: z.number().nonnegative().optional(),
+	availability: TurnOutcomeArtifactAvailabilitySchema,
+	location: TurnOutcomeArtifactLocationSchema,
+	capabilities: z.array(TurnOutcomeArtifactCapabilitySchema),
+	uri: z.string().optional(),
+	workspaceRelativePath: z.string().optional(),
+	shareUrl: z.string().url().optional(),
+	thumbnailUrl: z.string().optional(),
+	expiresAt: z.string().optional()
+});
+const TurnOutcomeChangedFileSchema = z.object({
+	path: z.string().min(1),
+	status: z.enum([
+		"added",
+		"modified",
+		"deleted",
+		"renamed"
+	]).optional(),
+	added: z.number().nonnegative().optional(),
+	removed: z.number().nonnegative().optional()
+});
+const TurnOutcomeChangeSetSchema = z.object({
+	changeSetId: z.string().min(1),
+	files: z.array(TurnOutcomeChangedFileSchema),
+	added: z.number().nonnegative(),
+	removed: z.number().nonnegative(),
+	diff: z.string(),
+	diffTruncated: z.boolean().optional(),
+	environment: z.enum([
+		"workspace",
+		"worktree",
+		"remote_runtime"
+	])
+});
+const TurnOutcomeEvidenceSchema = z.object({
+	evidenceId: z.string().min(1),
+	kind: z.enum([
+		"check",
+		"screenshot",
+		"video",
+		"log"
+	]),
+	label: z.string().min(1),
+	status: z.enum([
+		"passed",
+		"failed",
+		"warning"
+	]),
+	durationMs: z.number().nonnegative().optional(),
+	command: z.string().optional(),
+	artifactId: z.string().optional()
+});
+const TurnOutcomeSchema = z.object({
+	version: z.literal(1),
+	outcomeId: z.string().min(1),
+	runId: z.string().min(1),
+	turnId: z.string().min(1),
+	status: z.enum([
+		"succeeded",
+		"partial",
+		"failed"
+	]),
+	summary: z.string().optional(),
+	deliverables: z.array(TurnOutcomeDeliverableSchema),
+	changeSet: TurnOutcomeChangeSetSchema.optional(),
+	evidence: z.array(TurnOutcomeEvidenceSchema),
+	createdAt: z.string()
+});
+function parseTurnOutcome(value) {
+	const parsed = TurnOutcomeSchema.safeParse(value);
+	return parsed.success ? parsed.data : null;
+}
+//#endregion
+export { TurnOutcomeDeliverableSchema, parseTurnOutcome };

package/dist/src/agent/agent-instance-gateway.d.ts

@@ -44,7 +44,7 @@ export interface AgentInstanceGateway {
     /** Build the bounded, policy-filtered context used for this model turn. */
     prepareUserTurnContext(userMessage: AgentMessage, sessionKey: string, turnId: string): Promise<import('./memory/context/types.js').UserContextPlan>;
     /** Post-turn: sync external memory providers, queue next prefetch. */
-    afterAgentTurn(sessionKey: string, userPlainText: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
+    afterAgentTurn(sessionKey: string, userPlainText: string, turnId: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
     /** Bump the per-session "turns since memory review" counter. */
     beginBackgroundReviewUserTurn(sessionKey: string): void;
     /** Fire-and-forget review (memory + skill nudges) once the main turn finishes. */

package/dist/src/agent/agent-manager.d.ts

@@ -206,7 +206,7 @@ export declare class AgentManager implements AgentInstanceGateway {
      * After a completed turn: sync external providers and queue next-turn prefetch.
      * Delegates to {@link UserContextCoordinator}.
      */
-    afterAgentTurn(sessionKey: string, userPlainText: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
+    afterAgentTurn(sessionKey: string, userPlainText: string, turnId: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
     /**
      * Call once per user turn before the main embedded agent turn.
      * Delegates to {@link BackgroundReviewCoordinator}.

package/dist/src/agent/agent-manager.js

@@ -8,6 +8,7 @@ import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
 import { init_agent_scope, resolveAgentProfileDir } from "./agent-scope.js";
+import { init_session_key, parseSessionKey } from "../routing/session-key.js";
 import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, resolveBundledSkillsDir } from "../config/paths.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../auth/sync-provider-auth.js";
@@ -36,6 +37,7 @@ import { evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner } from "./em
 import { isMemorySubsystemEnabled } from "./memory/memory-config.js";
 import { UserContextCoordinator } from "./memory/user-context-coordinator.js";
 import { WorkspaceRuntimeRegistry } from "./workspace-runtime/registry.js";
+import { runTurnUnderstandingReview } from "./background-review/run-background-review.js";
 import { BackgroundReviewCoordinator } from "./background-review/coordinator.js";
 import { maybeRequestChannelExecApproval } from "../channels/exec-approval-runtime.js";
 import { checkBoundary } from "../agent-runtime/boundary-guard.js";
@@ -59,6 +61,7 @@ init_sync_provider_auth();
 init_providers();
 init_credentials();
 init_paths();
+init_session_key();
 const log = createLogger("AgentManager");
 var AgentManager = class {
 	agents = /* @__PURE__ */ new Map();
@@ -131,7 +134,6 @@ var AgentManager = class {
 		this.userContext = new UserContextCoordinator({
 			getConfig: () => this.config.config,
 			isEnabledForSession: (sessionKey) => this.isUserContextEnabledForSession(sessionKey),
-			getAgentIdForSession: (sk) => this.agents.get(sk)?.effectiveProfile.agentId ?? "main",
 			getWorkspaceIdForSession: (sk) => this.getResolvedWorkspaceForSession(sk),
 			getProjectIdForSession: (sk) => getSessionMetadata(sk)?.projectId,
 			getMemoryManagerForSession: (sk) => this.getMemoryManagerForSession(sk),
@@ -299,8 +301,21 @@ var AgentManager = class {
 	* After a completed turn: sync external providers and queue next-turn prefetch.
 	* Delegates to {@link UserContextCoordinator}.
 	*/
-	afterAgentTurn(sessionKey, userPlainText) {
-		return this.userContext.afterTurn(sessionKey, userPlainText);
+	async afterAgentTurn(sessionKey, userPlainText, turnId) {
+		await this.userContext.afterTurn(sessionKey, userPlainText);
+		if (!this.isUserContextEnabledForSession(sessionKey)) return void 0;
+		const parsed = parseSessionKey(sessionKey);
+		if (parsed && parsed.peerKind !== "direct") return void 0;
+		const instance = this.agents.get(sessionKey);
+		if (!instance) return void 0;
+		return runTurnUnderstandingReview({
+			sessionKey,
+			turnId,
+			userText: userPlainText,
+			mainAgent: instance.agent,
+			memoryManager: this.getMemoryManagerForSession(sessionKey),
+			getConfig: () => this.mergedConfig()
+		});
 	}
 	/**
 	* Call once per user turn before the main embedded agent turn.

package/dist/src/agent/background-review/prompts.d.ts

@@ -1,2 +1,8 @@
-export declare const MEMORY_REVIEW_USER_PROMPT = "Review the conversation above and identify durable user-understanding candidates.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, emotional-support preferences, boundaries, or how they want you to communicate?\n3. Has the user explicitly corrected a prior assumption? Prefer the correction and do not preserve the contradicted interpretation.\n\nReturn JSON only, with this shape:\n{\"candidates\":[{\"kind\":\"preference\",\"content\":\"...\",\"confidence\":0.8,\"importance\":0.7,\"durability\":\"durable\",\"sensitivity\":\"normal\",\"disclosurePolicy\":\"referenceable\",\"evidenceRefs\":[\"entry-id\"]}]}\n\nAllowed kinds: preference, boundary, relationship, routine, current_state, long_term_goal, project_context, task_lesson, derived_insight.\nEvery reviewed message is prefixed with an evidence_ref. Every candidate must list the exact one or more evidence_ref values that support it. Omit a candidate when no exact message supports it. Only include facts supported by the conversation and likely to matter in a future session. A temporary mood or one-off reaction is current context, not durable identity; omit it unless the user describes a recurring pattern that will matter later. Never include passwords, tokens, credentials, or speculative diagnoses. Use {\"candidates\":[]} when nothing qualifies.\n\nWrite each understanding as concise, neutral profile copy that can be shown directly to the person described, not as an internal note about \"the user\". Prefer a subject-omitted predicate or noun phrase. For example, write \u201C\u503E\u5411\u4F7F\u7528 pnpm \u4F5C\u4E3A\u5305\u7BA1\u7406\u5668\u201D or \u201Cxopc \u9879\u76EE\u7684\u6838\u5FC3\u5F00\u53D1\u8005\u201D, not \u201C\u7528\u6237\u503E\u5411\u4E8E\u4F7F\u7528 pnpm\u201D or \u201C\u7528\u6237\u662F xopc \u9879\u76EE\u7684\u5F00\u53D1\u8005\u201D; write \u201CPrefers pnpm as the package manager\u201D or \u201CCore maintainer of xopc\u201D, not \u201CThe user prefers pnpm\u201D or \u201CThe user is a maintainer of xopc\u201D. Do not begin with generic subject labels or pronouns such as \u201C\u7528\u6237\u201D, \u201C\u8BE5\u7528\u6237\u201D, \u201C\u6B64\u7528\u6237\u201D, \u201C\u4F60\u201D, \u201C\u6211\u201D, \u201Cthe user\u201D, \u201Cuser\u201D, \u201Cyou\u201D, or \u201CI\u201D.\n\nDo not turn a request about the current task into user understanding. Exclude requested outputs, follow-up instructions, project-note edits, investigations, and other one-off work. Every candidate must be a complete standalone profile statement or enduring pattern; never return a clause fragment beginning with a connector such as \"and\", \"also\", \"\u5E76\u4E14\", \"\u4EE5\u53CA\", or \"\u7684\u4E8B\u9879\". Use long_term_goal only when the person states an enduring personal goal, not when they ask the assistant to create, update, investigate, summarize, or track something.";
-export declare const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = "You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.";
+export declare const UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT = "You are xopc's user-understanding interpreter. You do not chat with the user and cannot write storage. Distinguish memory commands, memory questions, corrections, forgetting, durable user assertions, and ordinary task requests. Return strict JSON only. Never treat assistant text as evidence of a fact about the user.";
+export declare function buildUnderstandingInterpreterPrompt(options: {
+    mode: 'turn' | 'transcript';
+    availableTargets?: Array<{
+        id: string;
+        statement: string;
+    }>;
+}): string;

package/dist/src/agent/background-review/prompts.js

@@ -1,21 +1,34 @@
 import { USER_FACING_UNDERSTANDING_WRITING_GUIDANCE } from "../../user-context/understanding-writing.js";
 //#region src/agent/background-review/prompts.ts
-const MEMORY_REVIEW_USER_PROMPT = `Review the conversation above and identify durable user-understanding candidates.
+const UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT = `You are xopc's user-understanding interpreter. You do not chat with the user and cannot write storage. Distinguish memory commands, memory questions, corrections, forgetting, durable user assertions, and ordinary task requests. Return strict JSON only. Never treat assistant text as evidence of a fact about the user.`;
+function buildUnderstandingInterpreterPrompt(options) {
+	const targets = options.availableTargets?.length ? `\nOnly these understanding IDs may be targeted for confirm, correction, or forgetting:\n${options.availableTargets.map((item) => `- ${item.id}: ${item.statement}`).join("\n")}` : "\nNo existing understanding IDs are available to target.";
+	return `Interpret the evidence-tagged conversation above for ${options.mode === "turn" ? "the latest user turn" : "durable transcript synthesis"}.
 
-Focus on:
-1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
-2. Has the user expressed expectations about how you should behave, their work style, emotional-support preferences, boundaries, or how they want you to communicate?
-3. Has the user explicitly corrected a prior assumption? Prefer the correction and do not preserve the contradicted interpretation.
+Return exactly this JSON shape:
+{"intent":"none","candidates":[],"targetUnderstandingIds":[],"abstentionReason":"..."}
 
-Return JSON only, with this shape:
-{"candidates":[{"kind":"preference","content":"...","confidence":0.8,"importance":0.7,"durability":"durable","sensitivity":"normal","disclosurePolicy":"referenceable","evidenceRefs":["entry-id"]}]}
+Allowed intents: memory_create, memory_query, memory_confirm, memory_correct, memory_forget, user_assertion, task_request, none.
+
+Candidate shape:
+{"factKey":"communication:concise","statement":"...","kind":"preference","explicitness":"observed","durability":"durable","scopeHint":"global","confidence":0.8,"importance":0.7,"sensitivity":"normal","disclosurePolicy":"referenceable","evidence":[{"ref":"entry-id","quote":"exact quote from that user message"}],"selfContained":true,"unresolvedReferences":[]}
 
 Allowed kinds: preference, boundary, relationship, routine, current_state, long_term_goal, project_context, task_lesson, derived_insight.
-Every reviewed message is prefixed with an evidence_ref. Every candidate must list the exact one or more evidence_ref values that support it. Omit a candidate when no exact message supports it. Only include facts supported by the conversation and likely to matter in a future session. A temporary mood or one-off reaction is current context, not durable identity; omit it unless the user describes a recurring pattern that will matter later. Never include passwords, tokens, credentials, or speculative diagnoses. Use {"candidates":[]} when nothing qualifies.
 
-${USER_FACING_UNDERSTANDING_WRITING_GUIDANCE}
+Rules:
+- A question such as “Do you remember this goal?” is memory_query and creates no candidate.
+- A request to create, summarize, update, investigate, or track a goal is task_request, not a user goal.
+- Every candidate needs an exact quote from one or more user messages. Assistant messages may resolve context but never count as evidence.
+- Extract zero to eight independent candidates; do not collapse multiple facts into one.
+- factKey must be a stable language-neutral lowercase identifier using letters, digits, colons, or hyphens. Equivalent facts in different languages must use the same factKey.
+- Set selfContained=false and list unresolvedReferences for unresolved words such as this, that, it, 这个, 那个, or 它.
+- Omit temporary reactions and one-off task instructions.
+- Never include passwords, credentials, regulated identifiers, or speculative diagnoses.
+- For transcript mode, use explicitness=inferred unless the latest user message is itself an explicit memory command or correction.
+- If evidence is insufficient, return candidates=[] and explain abstentionReason.
 
-Do not turn a request about the current task into user understanding. Exclude requested outputs, follow-up instructions, project-note edits, investigations, and other one-off work. Every candidate must be a complete standalone profile statement or enduring pattern; never return a clause fragment beginning with a connector such as "and", "also", "并且", "以及", or "的事项". Use long_term_goal only when the person states an enduring personal goal, not when they ask the assistant to create, update, investigate, summarize, or track something.`;
-const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = `You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.`;
+${USER_FACING_UNDERSTANDING_WRITING_GUIDANCE}
+${targets}`;
+}
 //#endregion
-export { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT };
+export { UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT, buildUnderstandingInterpreterPrompt };

package/dist/src/agent/background-review/run-background-review.d.ts

@@ -1,7 +1,7 @@
 import { Agent } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
 import type { MemoryManager } from '../memory/manager.js';
-import type { UnderstandingCandidate } from '../memory/understanding/types.js';
+import type { UnderstandingReviewResult } from '../memory/understanding/types.js';
 import type { BackgroundReviewSettings } from './settings.js';
 export interface RunBackgroundReviewParams {
     sessionKey: string;
@@ -10,5 +10,10 @@ export interface RunBackgroundReviewParams {
     memoryManager: MemoryManager;
     getConfig: () => Config | undefined;
 }
-export declare function parseUnderstandingCandidates(raw: string): UnderstandingCandidate[];
+export interface RunTurnUnderstandingParams extends Omit<RunBackgroundReviewParams, 'settings'> {
+    turnId: string;
+    userText: string;
+    maxHistoryMessages?: number;
+}
+export declare function runTurnUnderstandingReview(params: RunTurnUnderstandingParams): Promise<UnderstandingReviewResult>;
 export declare function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void>;