@xopcai/xopc 0.0.188 → 0.0.189

package/dist/gateway/static/root/index.html

@@ -11,7 +11,7 @@
     <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png?v=20260713-1" />
     <link rel="manifest" href="/site.webmanifest?v=20260713-1" />
     <title>XOPC — Turn goals into loops. Keep what matters moving.</title>
-    <script type="module" crossorigin src="/assets/index-OJgiMh07.js"></script>
+    <script type="module" crossorigin src="/assets/index-BvR-i-m6.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-aKtaBQYM.js">
     <link rel="modulepreload" crossorigin href="/assets/preload-helper-zJ_50EbN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-BOUWij0V.js">
@@ -23,17 +23,17 @@
     <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-DPHK1VkS.js">
     <link rel="modulepreload" crossorigin href="/assets/check-DUBLcKHA.js">
     <link rel="modulepreload" crossorigin href="/assets/middleware-Pd0e8Igk.js">
-    <link rel="modulepreload" crossorigin href="/assets/messages-D02NNLCZ.js">
-    <link rel="modulepreload" crossorigin href="/assets/locale-store-D6hs74o5.js">
+    <link rel="modulepreload" crossorigin href="/assets/messages-CMjnbdbn.js">
+    <link rel="modulepreload" crossorigin href="/assets/locale-store-DUW5YE3R.js">
     <link rel="modulepreload" crossorigin href="/assets/cn-JdwAhgNB.js">
-    <link rel="modulepreload" crossorigin href="/assets/schemas-C6onAggk.js">
-    <link rel="modulepreload" crossorigin href="/assets/product-delivery-C8JbSj5Y.js">
+    <link rel="modulepreload" crossorigin href="/assets/schemas-zIBW3wiV.js">
+    <link rel="modulepreload" crossorigin href="/assets/product-delivery-tRr-7IxY.js">
     <link rel="modulepreload" crossorigin href="/assets/config-reload-event-Bjh2zoKp.js">
     <link rel="modulepreload" crossorigin href="/assets/copy-to-clipboard-HOJ79TWv.js">
-    <link rel="modulepreload" crossorigin href="/assets/gateway-startup-retry-B2DmdlwO.js">
-    <link rel="modulepreload" crossorigin href="/assets/activity-store--QoUGhiS.js">
-    <link rel="modulepreload" crossorigin href="/assets/theme-store-BRxdsmic.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-Cl5n1f_U.css">
+    <link rel="modulepreload" crossorigin href="/assets/gateway-startup-retry-DxhKNiCF.js">
+    <link rel="modulepreload" crossorigin href="/assets/activity-store-DTFKTPs8.js">
+    <link rel="modulepreload" crossorigin href="/assets/theme-store-BkJe7UDo.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-zybP34zk.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.0.188";
+var version = "0.0.189";
 //#endregion
 export { version };

package/dist/packages/endpoint-tools-protocol/src/index.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+const ENDPOINT_MAX_FILE_BYTES = 25 * 1024 * 1024;
+const ENDPOINT_INVOCATION_RECEIPT_TIMEOUT_MS = 3e3;
+const endpointKindSchema = z.enum([
+	"web",
+	"desktop",
+	"mobile"
+]);
+const endpointAvailabilitySchema = z.enum(["foreground", "background"]);
+const endpointEffectSchema = z.enum([
+	"read",
+	"write",
+	"destructive"
+]);
+const endpointConfirmationSchema = z.enum(["never", "always"]);
+const endpointResultKindSchema = z.enum([
+	"text",
+	"json",
+	"file"
+]);
+const identifierSchema = z.string().min(1).max(160);
+const turnTokenSchema = z.string().min(32).max(160).regex(/^[A-Za-z0-9_-]+$/);
+const turnOriginSchema = z.discriminatedUnion("type", [
+	z.strictObject({
+		type: z.literal("endpoint"),
+		endpointId: identifierSchema
+	}),
+	z.strictObject({
+		type: z.literal("channel"),
+		channel: z.string().min(1).max(64)
+	}),
+	z.strictObject({
+		type: z.literal("system"),
+		source: z.enum([
+			"cli",
+			"automation",
+			"heartbeat",
+			"workflow",
+			"internal"
+		])
+	})
+]);
+const endpointTurnClaimSchema = turnOriginSchema.options[0].extend({ token: turnTokenSchema });
+const messageIdSchema = z.uuid();
+const timestampSchema = z.number().int().nonnegative();
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const endpointToolDescriptorSchema = z.strictObject({
+	name: z.string().regex(/^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/).max(120),
+	title: z.string().min(1).max(120),
+	description: z.string().min(1).max(2e3),
+	inputSchema: jsonObjectSchema,
+	effect: endpointEffectSchema,
+	confirmation: endpointConfirmationSchema,
+	requiresForeground: z.boolean(),
+	requiredPermissions: z.array(z.string().min(1).max(120)).max(20),
+	timeoutMs: z.number().int().min(1e3).max(3e5),
+	maxConcurrency: z.number().int().min(1).max(4),
+	supportsCancellation: z.boolean(),
+	idempotent: z.boolean(),
+	resultKinds: z.array(endpointResultKindSchema).min(1).max(3)
+});
+const endpointPrincipalRegistrationSchema = z.strictObject({
+	principalId: identifierSchema,
+	displayName: z.string().min(1).max(120),
+	kind: endpointKindSchema,
+	platform: z.string().min(1).max(80),
+	publicKey: z.string().min(32).max(2048)
+});
+const endpointHelloPayloadSchema = z.strictObject({
+	principalId: identifierSchema,
+	endpointId: identifierSchema,
+	connectionInstanceId: z.uuid(),
+	displayName: z.string().min(1).max(120),
+	kind: endpointKindSchema,
+	platform: z.string().min(1).max(80),
+	appVersion: z.string().min(1).max(80),
+	availability: endpointAvailabilitySchema,
+	nonce: identifierSchema,
+	signedAt: timestampSchema,
+	signature: z.string().min(16).max(1024),
+	tools: z.array(endpointToolDescriptorSchema).max(100)
+});
+const toolInvokePayloadSchema = z.strictObject({
+	invocationId: z.uuid(),
+	toolCallId: identifierSchema,
+	toolName: endpointToolDescriptorSchema.shape.name,
+	arguments: jsonObjectSchema,
+	descriptorRevision: z.string().min(1).max(128),
+	confirmationRequired: z.boolean(),
+	deadlineAt: timestampSchema,
+	uploadGrant: z.strictObject({
+		path: z.string().startsWith("/").max(500),
+		token: identifierSchema,
+		maxBytes: z.number().int().positive(),
+		maxFiles: z.number().int().min(1).max(20),
+		expiresAt: timestampSchema
+	}).optional()
+});
+const toolCancelPayloadSchema = z.strictObject({
+	invocationId: z.uuid(),
+	reason: z.string().min(1).max(500)
+});
+const invocationPayloadSchema = z.strictObject({ invocationId: z.uuid() });
+const endpointToolContentSchema = z.discriminatedUnion("type", [
+	z.strictObject({
+		type: z.literal("text"),
+		text: z.string().max(256 * 1024)
+	}),
+	z.strictObject({
+		type: z.literal("json"),
+		value: z.unknown()
+	}),
+	z.strictObject({
+		type: z.literal("file"),
+		fileId: identifierSchema,
+		name: z.string().min(1).max(255),
+		mimeType: z.string().min(1).max(255),
+		size: z.number().int().nonnegative(),
+		sha256: z.string().regex(/^[a-f0-9]{64}$/)
+	})
+]);
+const endpointToolErrorCodeSchema = z.enum([
+	"ENDPOINT_OFFLINE",
+	"ENDPOINT_NOT_FOREGROUND",
+	"ENDPOINT_DISCONNECTED",
+	"TOOL_NOT_FOUND",
+	"TOOL_REVISION_MISMATCH",
+	"INVALID_ARGUMENTS",
+	"PERMISSION_DENIED",
+	"USER_DENIED",
+	"TOOL_BUSY",
+	"TOOL_TIMEOUT",
+	"TOOL_CANCELLED",
+	"RESULT_TOO_LARGE",
+	"PROTOCOL_ERROR"
+]);
+const envelope = (type, payload) => z.strictObject({
+	protocolVersion: z.literal(1),
+	messageId: messageIdSchema,
+	type: z.literal(type),
+	sentAt: timestampSchema,
+	payload
+});
+const clientEndpointMessageSchema = z.discriminatedUnion("type", [
+	envelope("endpoint.availability_changed", z.strictObject({ availability: endpointAvailabilitySchema })),
+	envelope("tool.received", invocationPayloadSchema),
+	envelope("tool.progress", z.strictObject({
+		invocationId: z.uuid(),
+		message: z.string().max(500).optional(),
+		percent: z.number().min(0).max(100).optional()
+	})),
+	envelope("tool.result", z.strictObject({
+		invocationId: z.uuid(),
+		content: z.array(endpointToolContentSchema).min(1).max(20),
+		details: jsonObjectSchema.optional()
+	})),
+	envelope("tool.error", z.strictObject({
+		invocationId: z.uuid(),
+		code: endpointToolErrorCodeSchema,
+		message: z.string().min(1).max(2e3)
+	})),
+	envelope("tool.cancelled", invocationPayloadSchema)
+]);
+const serverEndpointMessageSchema = z.discriminatedUnion("type", [envelope("tool.invoke", toolInvokePayloadSchema), envelope("tool.cancel", toolCancelPayloadSchema)]);
+function canonicalJson(value) {
+	if (value === null) return "null";
+	if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("Canonical JSON only supports finite numbers");
+		return JSON.stringify(value);
+	}
+	if (typeof value !== "object") throw new Error(`Canonical JSON does not support ${typeof value}`);
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error("Canonical JSON only supports plain objects");
+	const record = value;
+	return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+function endpointHelloSigningPayload(payload) {
+	const { signature: _signature, ...unsigned } = payload;
+	return canonicalJson(unsigned);
+}
+//#endregion
+export { ENDPOINT_INVOCATION_RECEIPT_TIMEOUT_MS, ENDPOINT_MAX_FILE_BYTES, canonicalJson, clientEndpointMessageSchema, endpointHelloPayloadSchema, endpointHelloSigningPayload, endpointPrincipalRegistrationSchema, endpointTurnClaimSchema, serverEndpointMessageSchema, turnOriginSchema };

package/dist/packages/realtime-client/src/index.js

@@ -0,0 +1,199 @@
+import { parseServerRealtimeMessage } from "../../realtime-protocol/src/index.js";
+//#region packages/realtime-client/src/index.ts
+function clientMessage(kind, payload) {
+	return {
+		protocolVersion: 1,
+		messageId: crypto.randomUUID(),
+		kind,
+		sentAt: Date.now(),
+		payload
+	};
+}
+function frameText(data) {
+	if (typeof data === "string") return data;
+	if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+	if (ArrayBuffer.isView(data)) {
+		const bytes = Uint8Array.from(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+		return new TextDecoder().decode(bytes);
+	}
+	throw new Error("Realtime server sent a non-text frame");
+}
+var RealtimeClient = class {
+	desiredSubscriptions = /* @__PURE__ */ new Map();
+	cursors = /* @__PURE__ */ new Map();
+	socket;
+	reconnectTimer;
+	heartbeatTimer;
+	generation = 0;
+	reconnectAttempts = 0;
+	shouldReconnect = false;
+	ready = false;
+	endpointBinding;
+	constructor(options) {
+		this.options = options;
+	}
+	connect() {
+		if (this.shouldReconnect) return;
+		this.shouldReconnect = true;
+		this.open(false);
+	}
+	disconnect() {
+		this.shouldReconnect = false;
+		this.generation += 1;
+		this.clearTimers();
+		this.ready = false;
+		this.endpointBinding?.onDisconnected?.();
+		this.socket?.close(1e3, "Client disconnected");
+		this.socket = void 0;
+		this.options.onStateChange?.("disconnected");
+	}
+	reconnect() {
+		this.generation += 1;
+		this.clearTimers();
+		this.ready = false;
+		this.endpointBinding?.onDisconnected?.();
+		this.socket?.close(1e3, "Client reconnecting");
+		this.socket = void 0;
+		this.reconnectAttempts = 0;
+		this.shouldReconnect = true;
+		this.open(true);
+	}
+	subscribe(topic, afterSeq) {
+		this.desiredSubscriptions.set(topic, afterSeq);
+		if (this.ready) {
+			this.sendSubscriptions([{
+				topic,
+				afterSeq: afterSeq ?? this.cursors.get(topic)
+			}]);
+			this.desiredSubscriptions.set(topic, void 0);
+		}
+	}
+	unsubscribe(topic) {
+		this.desiredSubscriptions.delete(topic);
+		if (this.ready) this.send(clientMessage("realtime.unsubscribe", { topics: [topic] }));
+	}
+	sendEndpointMessage(message) {
+		if (!this.ready) throw new Error("Realtime connection is not ready");
+		this.send(clientMessage("endpoint.message", message));
+	}
+	setEndpoint(binding) {
+		this.endpointBinding = binding;
+		if (this.shouldReconnect) this.reconnect();
+	}
+	clearEndpoint(binding) {
+		if (binding && this.endpointBinding !== binding) return;
+		const previous = this.endpointBinding;
+		this.endpointBinding = void 0;
+		previous?.onDisconnected?.();
+		if (this.shouldReconnect) this.reconnect();
+	}
+	async open(reconnecting) {
+		const generation = ++this.generation;
+		this.options.onStateChange?.(reconnecting ? "reconnecting" : "connecting");
+		try {
+			const [ticket, endpoint] = await Promise.all([this.options.issueTicket(), this.endpointBinding?.createHello()]);
+			if (!this.shouldReconnect || generation !== this.generation) return;
+			const socket = this.options.createWebSocket(this.options.getWebSocketUrl());
+			this.socket = socket;
+			socket.onopen = () => {
+				if (generation !== this.generation) return;
+				const subscriptions = [...this.desiredSubscriptions].map(([topic, afterSeq]) => ({
+					topic,
+					afterSeq: afterSeq ?? this.cursors.get(topic)
+				}));
+				for (const topic of this.desiredSubscriptions.keys()) this.desiredSubscriptions.set(topic, void 0);
+				this.send(clientMessage("realtime.hello", {
+					ticket,
+					clientId: this.options.clientId,
+					clientKind: this.options.clientKind,
+					subscriptions,
+					...endpoint ? { endpoint } : {}
+				}));
+			};
+			socket.onmessage = (event) => {
+				if (generation !== this.generation) return;
+				try {
+					this.handleServerMessage(frameText(event.data));
+				} catch (error) {
+					this.fail(error instanceof Error ? error.message : "Invalid realtime server message");
+				}
+			};
+			socket.onerror = () => {
+				if (generation === this.generation) this.options.onStateChange?.("reconnecting");
+			};
+			socket.onclose = (event) => {
+				if (generation !== this.generation) return;
+				this.ready = false;
+				this.endpointBinding?.onDisconnected?.();
+				this.socket = void 0;
+				this.clearHeartbeat();
+				if (this.shouldReconnect) this.scheduleReconnect(event.reason || `WebSocket closed (${event.code ?? 0})`);
+				else this.options.onStateChange?.("disconnected");
+			};
+		} catch (error) {
+			if (generation !== this.generation) return;
+			this.scheduleReconnect(error instanceof Error ? error.message : "Realtime connection failed");
+		}
+	}
+	handleServerMessage(text) {
+		const message = parseServerRealtimeMessage(JSON.parse(text));
+		if (message.kind === "realtime.ready") {
+			this.ready = true;
+			this.reconnectAttempts = 0;
+			this.options.onStateChange?.("connected");
+			if (message.payload.endpoint) this.endpointBinding?.onReady(message.payload.endpoint);
+			this.clearHeartbeat();
+			this.heartbeatTimer = setInterval(() => {
+				if (this.ready) this.send(clientMessage("realtime.ping", {}));
+			}, message.payload.heartbeatIntervalMs);
+		} else if (message.kind === "realtime.event") {
+			this.cursors.set(message.payload.topic, message.payload.seq);
+			this.options.onEvent?.(message.payload);
+		} else if (message.kind === "realtime.gap") {
+			this.cursors.set(message.payload.topic, message.payload.earliestSeq - 1);
+			this.options.onGap?.(message.payload);
+		} else if (message.kind === "realtime.error") this.options.onStateChange?.("error", message.payload.message);
+		else if (message.kind === "endpoint.message") {
+			this.endpointBinding?.onMessage(message.payload);
+			this.options.onEndpointMessage?.(message.payload);
+		}
+	}
+	sendSubscriptions(subscriptions) {
+		this.send(clientMessage("realtime.subscribe", { subscriptions }));
+	}
+	send(message) {
+		if (!this.socket || this.socket.readyState !== 1) return;
+		this.socket.send(JSON.stringify(message));
+	}
+	scheduleReconnect(error) {
+		if (!this.shouldReconnect) return;
+		this.reconnectAttempts += 1;
+		const max = this.options.maxReconnectAttempts;
+		if (max !== void 0 && this.reconnectAttempts > max) {
+			this.shouldReconnect = false;
+			this.options.onStateChange?.("error", error);
+			return;
+		}
+		this.options.onStateChange?.("reconnecting", error);
+		const delay = Math.min(3e4, 1e3 * 2 ** Math.min(this.reconnectAttempts - 1, 5));
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = void 0;
+			this.open(true);
+		}, delay);
+	}
+	fail(message) {
+		this.options.onStateChange?.("error", message);
+		this.socket?.close(4400, "Invalid server message");
+	}
+	clearHeartbeat() {
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = void 0;
+	}
+	clearTimers() {
+		if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = void 0;
+		this.clearHeartbeat();
+	}
+};
+//#endregion
+export { RealtimeClient };

package/dist/packages/realtime-protocol/src/index.js

@@ -0,0 +1,83 @@
+import { clientEndpointMessageSchema, endpointHelloPayloadSchema, serverEndpointMessageSchema } from "../../endpoint-tools-protocol/src/index.js";
+import { z } from "zod";
+const REALTIME_MAX_CLIENT_FRAME_BYTES = 256 * 1024;
+const REALTIME_HELLO_TIMEOUT_MS = 5e3;
+const REALTIME_HEARTBEAT_INTERVAL_MS = 15e3;
+const REALTIME_HEARTBEAT_TIMEOUT_MS = 45e3;
+const realtimeClientKindSchema = z.enum([
+	"web",
+	"desktop",
+	"mobile",
+	"tui",
+	"mcp"
+]);
+const realtimeTopicSchema = z.string().min(1).max(512);
+const realtimeEventNameSchema = z.string().regex(/^[a-z][a-z0-9_.-]*$/).max(160);
+const messageIdSchema = z.uuid();
+const timestampSchema = z.number().int().nonnegative();
+const sequenceSchema = z.number().int().positive();
+const envelope = (kind, payload) => z.strictObject({
+	protocolVersion: z.literal(1),
+	messageId: messageIdSchema,
+	kind: z.literal(kind),
+	sentAt: timestampSchema,
+	payload
+});
+const realtimeSubscriptionSchema = z.strictObject({
+	topic: realtimeTopicSchema,
+	afterSeq: z.number().int().nonnegative().optional()
+});
+const clientRealtimeMessageSchema = z.discriminatedUnion("kind", [
+	envelope("realtime.hello", z.strictObject({
+		ticket: z.string().min(32).max(512),
+		clientId: z.string().min(1).max(160),
+		clientKind: realtimeClientKindSchema,
+		subscriptions: z.array(realtimeSubscriptionSchema).max(100).default([]),
+		endpoint: endpointHelloPayloadSchema.optional()
+	})),
+	envelope("realtime.subscribe", z.strictObject({ subscriptions: z.array(realtimeSubscriptionSchema).min(1).max(100) })),
+	envelope("realtime.unsubscribe", z.strictObject({ topics: z.array(realtimeTopicSchema).min(1).max(100) })),
+	envelope("realtime.ping", z.strictObject({})),
+	envelope("endpoint.message", clientEndpointMessageSchema)
+]);
+const realtimeEventPayloadSchema = z.strictObject({
+	topic: realtimeTopicSchema,
+	seq: sequenceSchema,
+	event: realtimeEventNameSchema,
+	data: z.unknown()
+});
+const serverRealtimeMessageSchema = z.discriminatedUnion("kind", [
+	envelope("realtime.ready", z.strictObject({
+		connectionId: z.uuid(),
+		heartbeatIntervalMs: z.literal(REALTIME_HEARTBEAT_INTERVAL_MS),
+		heartbeatTimeoutMs: z.literal(REALTIME_HEARTBEAT_TIMEOUT_MS),
+		endpoint: z.strictObject({
+			endpointId: z.string().min(1).max(160),
+			turnToken: z.string().min(32).max(160)
+		}).optional()
+	})),
+	envelope("realtime.event", realtimeEventPayloadSchema),
+	envelope("realtime.gap", z.strictObject({
+		topic: realtimeTopicSchema,
+		requestedSeq: z.number().int().nonnegative(),
+		earliestSeq: sequenceSchema
+	})),
+	envelope("realtime.pong", z.strictObject({})),
+	envelope("realtime.error", z.strictObject({
+		code: z.string().min(1).max(80),
+		message: z.string().min(1).max(500)
+	})),
+	envelope("endpoint.message", serverEndpointMessageSchema)
+]);
+function parseClientRealtimeMessage(value) {
+	return clientRealtimeMessageSchema.parse(value);
+}
+function parseServerRealtimeMessage(value) {
+	return serverRealtimeMessageSchema.parse(value);
+}
+function parseClientRealtimeJsonFrame(text) {
+	if (new TextEncoder().encode(text).byteLength > 262144) throw new Error(`Realtime client frame exceeds ${REALTIME_MAX_CLIENT_FRAME_BYTES} bytes`);
+	return JSON.parse(text);
+}
+//#endregion
+export { REALTIME_HEARTBEAT_INTERVAL_MS, REALTIME_HEARTBEAT_TIMEOUT_MS, REALTIME_HELLO_TIMEOUT_MS, REALTIME_MAX_CLIENT_FRAME_BYTES, parseClientRealtimeJsonFrame, parseClientRealtimeMessage, parseServerRealtimeMessage, realtimeClientKindSchema, realtimeEventNameSchema, realtimeTopicSchema };

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

@@ -70,6 +70,7 @@ export interface AgentManagerConfig {
     model?: string;
     config?: Config;
     extensionRegistry?: ExtensionRegistry;
+    endpointTools?: import('../endpoint-tools/index.js').EndpointToolRuntime;
     hookRunner?: import('../extensions/index.js').ExtensionHookRunner;
     bus: MessageBus;
     getCurrentContext: () => SessionContext | null;

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

@@ -225,6 +225,7 @@ var AgentManager = class {
 		return {
 			workspace: this.baseWorkspacePath,
 			extensionRegistry: this.config.extensionRegistry,
+			endpointTools: this.config.endpointTools,
 			getCurrentContext: this.config.getCurrentContext,
 			hookRunner: this.config.hookRunner,
 			bus: this.config.bus,

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

@@ -1,2 +1,2 @@
-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\",\"tags\":[\"background-review\"]}]}\n\nAllowed kinds: preference, boundary, relationship, project_context, commitment, routine, personal_logistics, open_question, milestone, current_state, task_lesson, tool_preference, long_term_goal, derived_insight.\nOnly 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.";
+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\",\"tags\":[\"background-review\"]}]}\n\nAllowed kinds: preference, boundary, relationship, project_context, commitment, routine, personal_logistics, open_question, milestone, current_state, task_lesson, tool_preference, long_term_goal, derived_insight.\nOnly 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\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 statement about the user or an 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 user 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.";

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

@@ -10,7 +10,9 @@ Return JSON only, with this shape:
 {"candidates":[{"kind":"preference","content":"...","confidence":0.8,"importance":0.7,"durability":"durable","sensitivity":"normal","disclosurePolicy":"referenceable","tags":["background-review"]}]}
 
 Allowed kinds: preference, boundary, relationship, project_context, commitment, routine, personal_logistics, open_question, milestone, current_state, task_lesson, tool_preference, long_term_goal, derived_insight.
-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.`;
+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.
+
+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 statement about the user or an enduring pattern; never return a clause fragment beginning with a connector such as "and", "also", "并且", "以及", or "的事项". Use long_term_goal only when the user 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.`;
 //#endregion
 export { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT };

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

@@ -1,6 +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 { BackgroundReviewSettings } from './settings.js';
 export interface RunBackgroundReviewParams {
     sessionKey: string;
@@ -9,4 +10,5 @@ export interface RunBackgroundReviewParams {
     memoryManager: MemoryManager;
     getConfig: () => Config | undefined;
 }
+export declare function parseUnderstandingCandidates(raw: string): UnderstandingCandidate[];
 export declare function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void>;

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

@@ -6,6 +6,7 @@ import { createExtensionAwareStreamFn } from "../../providers/extension-stream-b
 import { extractTextContent } from "../context/workspace.js";
 import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
 import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
+import { isDurableUnderstandingCandidate } from "../../user-context/understandingQuality.js";
 import { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT } from "./prompts.js";
 import { Agent } from "@earendil-works/pi-agent-core";
 //#region src/agent/background-review/run-background-review.ts
@@ -61,13 +62,15 @@ function parseUnderstandingCandidates(raw) {
 			const item = value;
 			if (!ALLOWED_UNDERSTANDING_KINDS.has(item.kind)) continue;
 			if (typeof item.content !== "string" || item.content.trim().length < 4) continue;
+			const kind = item.kind;
+			if (!isDurableUnderstandingCandidate(kind, item.content)) continue;
 			const confidence = typeof item.confidence === "number" ? item.confidence : .65;
 			const importance = typeof item.importance === "number" ? item.importance : .5;
 			const durability = item.durability === "ephemeral" || item.durability === "recurring" ? item.durability : "durable";
 			const sensitivity = ALLOWED_SENSITIVITIES.has(item.sensitivity) ? item.sensitivity : "personal";
 			const disclosurePolicy = item.disclosurePolicy === "silent" || item.disclosurePolicy === "ask_before_reference" ? item.disclosurePolicy : "referenceable";
 			output.push({
-				kind: item.kind,
+				kind,
 				content: item.content.trim(),
 				confidence: Math.max(0, Math.min(1, confidence)),
 				importance: Math.max(0, Math.min(1, importance)),
@@ -133,4 +136,4 @@ async function runBackgroundReviewTurn(params) {
 	await runUnderstandingReview(params);
 }
 //#endregion
-export { runBackgroundReviewTurn };
+export { parseUnderstandingCandidates, runBackgroundReviewTurn };

package/dist/src/agent/client-error-format.d.ts

@@ -16,5 +16,5 @@ export declare function formatAgentRunErrorForClient(rawError: string, context?:
     provider?: string;
     modelRef?: string;
 }): string;
-/** Human-readable text for TUI/CLI when SSE carries structured JSON. */
+/** Human-readable text for TUI/CLI when a run event carries structured JSON. */
 export declare function formatAgentRunErrorForDisplay(content: string): string;

package/dist/src/agent/client-error-format.js

@@ -87,7 +87,7 @@ function formatAgentRunErrorForClient(rawError, context) {
 	}
 	return JSON.stringify(payload);
 }
-/** Human-readable text for TUI/CLI when SSE carries structured JSON. */
+/** Human-readable text for TUI/CLI when a run event carries structured JSON. */
 function formatAgentRunErrorForDisplay(content) {
 	const trimmed = content.trim();
 	if (trimmed.startsWith("Error: ")) return trimmed.slice(7);

package/dist/src/agent/external-tools/endpoint-provider.d.ts

@@ -0,0 +1,17 @@
+import type { AgentToolResult } from '@earendil-works/pi-agent-core';
+import type { EndpointToolRuntime } from '../../endpoint-tools/index.js';
+import type { ExternalToolDescriptor, ExternalToolExecutionContext, ExternalToolProvider, ExternalToolSearchHit, ExternalToolTurnContext } from './types.js';
+export interface EndpointToolProviderDeps {
+    runtime: EndpointToolRuntime;
+    getCurrentContext: () => ExternalToolTurnContext | null;
+}
+export declare class EndpointToolProvider implements ExternalToolProvider {
+    private readonly deps;
+    readonly source: "endpoint";
+    constructor(deps: EndpointToolProviderDeps);
+    search(_query: string): Promise<ExternalToolSearchHit[]>;
+    describe(toolRef: string): Promise<ExternalToolDescriptor | undefined>;
+    execute(toolRef: string, args: Record<string, unknown>, _approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<AgentToolResult<Record<string, unknown>>>;
+    private currentEndpoint;
+    private resolve;
+}