@xopcai/xopc 0.0.248 → 0.0.249

package/dist/src/connectors/connection-capabilities.js

@@ -0,0 +1,37 @@
+//#region src/connectors/connection-capabilities.ts
+/** Supported actions for the task capabilities offered by connection candidates. */
+const CAPABILITY_ACTIONS = {
+	"composio-slack": { "messages.search": ["SLACK_SEARCH_ALL", "SLACK_SEARCH_MESSAGES"] },
+	"composio-gmail": {
+		"email.search": ["GMAIL_FETCH_EMAILS"],
+		"email.read": ["GMAIL_FETCH_EMAILS", "GMAIL_GET_EMAIL"]
+	},
+	"composio-outlook": {
+		"email.search": ["OUTLOOK_LIST_MESSAGES"],
+		"email.read": ["OUTLOOK_LIST_MESSAGES", "OUTLOOK_GET_MESSAGE"]
+	},
+	"composio-googlecalendar": { "calendar.read": ["GOOGLECALENDAR_EVENTS_LIST", "GOOGLECALENDAR_FIND_EVENT"] },
+	"composio-googledrive": {
+		"files.search": ["GOOGLEDRIVE_FIND_FILE", "GOOGLEDRIVE_LIST_FILES"],
+		"files.read": [
+			"GOOGLEDRIVE_DOWNLOAD_FILE",
+			"GOOGLEDRIVE_GET_FILE",
+			"GOOGLEDRIVE_GET_FILE_METADATA"
+		]
+	},
+	"composio-notion": {
+		"pages.search": ["NOTION_SEARCH"],
+		"pages.read": ["NOTION_FETCH_PAGE"]
+	}
+};
+function isToolInputSchema(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value) && value.type === "object");
+}
+function capabilityActions(need) {
+	return need.capabilities.map((capability) => /^[A-Z]+_/.test(capability) ? [capability] : CAPABILITY_ACTIONS[need.connectorId]?.[capability] ?? []);
+}
+function missingConnectionCapabilities(need, actions) {
+	return capabilityActions(need).flatMap((alternatives, index) => alternatives.some((action) => actions.has(action)) ? [] : [need.capabilities[index]]);
+}
+//#endregion
+export { capabilityActions, isToolInputSchema, missingConnectionCapabilities };

package/dist/src/connectors/connection-recovery-service.d.ts

@@ -0,0 +1,42 @@
+import type { Config } from '../config/schema.js';
+import type { SessionInput } from '../storage/sqlite/session-input-repository.js';
+import { ComposioSessionsAdapter } from './composio-sessions.js';
+import type { ConnectionWaitSnapshot } from '@xopcai/gateway-contract';
+export type ConnectionAction = {
+    waitId: string;
+    expectedSessionId: string;
+    expectedVersion: number;
+    idempotencyKey: string;
+    action: 'connect' | 'check' | 'continue' | 'skip' | 'cancel' | 'select_account' | 'confirm_scope' | 'replace_source';
+    needKey?: string;
+    accountId?: string;
+    candidateRef?: string;
+};
+/** Authorization lives at click time. Chat history contains only immutable explanations. */
+export declare class ConnectionRecoveryService {
+    private readonly deps;
+    private readonly busy;
+    private timer?;
+    private polling;
+    start(): void;
+    stop(): void;
+    poll(): Promise<void>;
+    constructor(deps: {
+        getConfig: () => Config;
+        saveConfig: (config: Config) => Promise<{
+            saved: boolean;
+            error?: string;
+        }>;
+        drain: (sessionKey: string) => void;
+        adapter?: ComposioSessionsAdapter;
+    });
+    private get adapter();
+    snapshot(sessionKey: string): ConnectionWaitSnapshot;
+    private view;
+    private checkCapabilities;
+    preflight(input: SessionInput): Promise<boolean>;
+    act(sessionKey: string, action: ConnectionAction): Promise<{
+        snapshot: ConnectionWaitSnapshot;
+        authorizationUrl?: string;
+    }>;
+}

package/dist/src/connectors/connection-recovery-service.js

@@ -0,0 +1,396 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { getSqliteDatabase } from "../storage/sqlite/transaction.js";
+import { cancelConnectionObjective, getActiveConnectionWait, getConnectionWait, listConnectionWaitsToCheck, publishConnectionWait, queueConnectionResolution, updateConnectionWait } from "../storage/sqlite/connection-wait-repository.js";
+import { readCurrentSessionId } from "../storage/sqlite/session-repository.js";
+import { getSessionInputState } from "../storage/sqlite/session-input-repository.js";
+import { getConnectorInstallation, listConnectorConnections, upsertConnectorInstallation } from "../storage/sqlite/connector-repository.js";
+import { ComposioSessionsAdapter } from "./composio-sessions.js";
+import { getConfiguredComposioAuthConfigs, isComposioActionAllowedByCatalog, scopeForComposioAction } from "./composio.js";
+import { getConnectorDefinition } from "./catalog.js";
+import { capabilityActions, isToolInputSchema, missingConnectionCapabilities } from "./connection-capabilities.js";
+import { connectorPrincipalForSession } from "./principal.js";
+import { resolveConnectionCandidate } from "./connection-candidates.js";
+import { getConnectorInstance } from "./instances.js";
+import { installConnector } from "./install.js";
+import { persistConfigMutation } from "../config/config-mutation.js";
+import { randomUUID } from "node:crypto";
+//#region src/connectors/connection-recovery-service.ts
+init_logger();
+const log = createLogger("Connectors:Recovery");
+const SCOPE_ORDER = {
+	read: 1,
+	write: 2,
+	admin: 3
+};
+const INTENT_TTL = 30 * 6e4;
+const ATTEMPT_TTL = 10 * 6e4;
+/** Authorization lives at click time. Chat history contains only immutable explanations. */
+var ConnectionRecoveryService = class {
+	busy = /* @__PURE__ */ new Set();
+	timer;
+	polling = false;
+	start() {
+		if (this.timer) return;
+		this.timer = setInterval(() => {
+			this.poll();
+		}, 5e3);
+		this.timer.unref();
+		this.poll();
+	}
+	stop() {
+		clearInterval(this.timer);
+		this.timer = void 0;
+	}
+	async poll() {
+		if (this.polling) return;
+		this.polling = true;
+		try {
+			for (const wait of listConnectionWaitsToCheck()) {
+				if (this.busy.has(wait.sessionKey)) continue;
+				await this.act(wait.sessionKey, {
+					waitId: wait.id,
+					expectedSessionId: wait.sessionId,
+					expectedVersion: wait.version,
+					idempotencyKey: randomUUID(),
+					action: "check"
+				}).catch(() => {});
+			}
+		} finally {
+			this.polling = false;
+		}
+	}
+	constructor(deps) {
+		this.deps = deps;
+	}
+	get adapter() {
+		return this.deps.adapter ?? new ComposioSessionsAdapter();
+	}
+	snapshot(sessionKey) {
+		if (!connectorPrincipalForSession(sessionKey).isLocalOwner) throw new Error("This connection belongs to another principal.");
+		const sessionId = readCurrentSessionId(getSqliteDatabase(), sessionKey);
+		if (!sessionId) throw new Error("SESSION_CHANGED");
+		const wait = getActiveConnectionWait(sessionKey);
+		return {
+			sessionId,
+			revision: getSessionInputState(sessionKey).revision,
+			wait: wait ? this.view(wait) : null
+		};
+	}
+	view(wait, verifiedIds) {
+		const needs = wait.needs.map((need) => {
+			const instance = getConnectorInstance(this.deps.getConfig(), need.connectorId);
+			const installation = getConnectorInstallation(`${need.connectorId}-${wait.principalId}`);
+			const scopeBlocked = Math.max(1, ...need.capabilities.filter((capability) => /^[A-Z]+_/.test(capability)).map((capability) => SCOPE_ORDER[scopeForComposioAction(capability).scope])) > SCOPE_ORDER[installation?.maxScope ?? "read"];
+			const blocked = scopeBlocked || instance?.enabled === false || installation?.enabled === false || Boolean(installation?.allowedAgentIds.length && !installation.allowedAgentIds.includes(wait.agentId));
+			const all = listConnectorConnections({
+				principalId: wait.principalId,
+				connectorId: need.connectorId
+			});
+			const active = all.filter((connection) => connection.status === "active" && (!verifiedIds || verifiedIds.has(connection.id)) && (!need.accountId || connection.accountId === need.accountId) && (!installation?.selectedConnectionIds.length || installation.selectedConnectionIds.includes(connection.id)));
+			const selected = !verifiedIds && need.unavailable ? void 0 : need.attempt ? active.find((connection) => connection.providerConnectionId === need.attempt?.connectionId) : need.connectionId ? active.find((connection) => connection.id === need.connectionId) : active.length === 1 && !need.accountSelector ? active[0] : void 0;
+			const phase = blocked || selected && need.capabilityError ? "blocked" : selected && instance ? "ready" : active.length > 1 || need.accountSelector && active.length > 0 && !need.connectionId ? "choose_account" : need.attempt && need.attempt.expiresAt > Date.now() ? "authorizing" : need.unavailable || all.some((connection) => [
+				"expired",
+				"revoked",
+				"failed"
+			].includes(connection.status)) ? "reconnect" : "connect";
+			const alternatives = ["composio-gmail", "composio-outlook"].includes(need.connectorId) ? ["composio-gmail", "composio-outlook"].filter((id) => id !== need.connectorId).map((id) => ({
+				candidateRef: id,
+				label: getConnectorDefinition(id)?.displayName ?? id
+			})) : [];
+			return {
+				...need,
+				alternatives,
+				connectionId: selected?.id ?? need.connectionId,
+				phase,
+				accounts: active.map((connection) => ({
+					id: connection.id,
+					label: connection.alias ?? String(connection.identity.email ?? connection.identity.name ?? connection.id)
+				})),
+				...need.capabilityError && selected ? { reason: need.capabilityError } : {},
+				...blocked ? { reason: scopeBlocked ? "This action needs broader permissions. Review connector permissions in settings." : "This app is disabled or unavailable to the current agent. Review connector settings." } : {}
+			};
+		});
+		const ready = needs.every((need) => need.phase === "ready");
+		const review = wait.reviewRequired || Date.now() - wait.createdAt > INTENT_TTL && !wait.scopeConfirmedAt;
+		const { intent: _intent, checkpoint: _checkpoint, ...visible } = wait;
+		return {
+			...visible,
+			needs,
+			timeRange: wait.checkpoint.timeRange,
+			phase: wait.status === "queued" ? "queued" : ready ? review ? "review_scope" : "ready" : "needs_connection"
+		};
+	}
+	async checkCapabilities(wait, verified) {
+		const views = this.view({
+			...wait,
+			needs: wait.needs.map((need) => ({
+				...need,
+				capabilityError: void 0
+			}))
+		}, verified).needs;
+		return Promise.all(wait.needs.map(async (need) => {
+			if (views.find((view) => view.key === need.key)?.phase !== "ready") return {
+				...need,
+				capabilityError: void 0
+			};
+			try {
+				const definition = getConnectorDefinition(need.connectorId);
+				if (definition?.runtime.type !== "composio" || definition.runtime.role !== "toolkit") throw new Error("Unsupported connector");
+				const toolkit = definition.runtime.toolkit;
+				const result = await (await this.adapter.createSession({
+					principalId: wait.principalId,
+					toolkits: [toolkit],
+					authConfigs: getConfiguredComposioAuthConfigs(this.deps.getConfig(), [toolkit])
+				})).search({
+					query: `${toolkit} ${need.capabilities.join(" ")} ${capabilityActions(need).flat().join(" ")}`,
+					toolkits: [toolkit]
+				});
+				const schemas = result && typeof result === "object" ? result.toolSchemas : void 0;
+				const missing = missingConnectionCapabilities(need, new Set(Object.entries(schemas && typeof schemas === "object" ? schemas : {}).filter(([action, value]) => value && typeof value === "object" && isToolInputSchema(value.inputSchema) && isComposioActionAllowedByCatalog(action)).map(([action]) => action)));
+				if (missing.length) log.warn({
+					sessionKey: wait.sessionKey,
+					connectorId: need.connectorId,
+					missingCapabilities: missing
+				}, "Connected app lacks required tool contracts");
+				return {
+					...need,
+					capabilityError: missing.length ? `${need.label} is connected, but the required tools are unavailable. Retry the tool check; reconnecting will not fix this.` : void 0
+				};
+			} catch (err) {
+				log.warn({
+					err,
+					sessionKey: wait.sessionKey,
+					connectorId: need.connectorId
+				}, "Connected app capability check failed");
+				return {
+					...need,
+					capabilityError: `${need.label} is connected, but its tools could not be checked. Retry the tool check.`
+				};
+			}
+		}));
+	}
+	async preflight(input) {
+		if (input.kind !== "connection_resume") return true;
+		const wait = input.payload ? getConnectionWait(input.payload.waitId) : void 0;
+		if (!wait || wait.status !== "queued" || wait.queuedInputId !== input.id || wait.sessionId !== readCurrentSessionId(getSqliteDatabase(), input.sessionKey)) return false;
+		if (wait.resolution === "skipped") return true;
+		try {
+			const fresh = await this.adapter.syncConnections({ principalId: wait.principalId });
+			const verified = new Set(fresh.filter((item) => item.status === "active").map((item) => item.id));
+			wait.needs = await this.checkCapabilities(wait, verified);
+			const ready = this.view(wait, verified).needs.every((need) => need.phase === "ready");
+			wait.needs = wait.needs.map((need) => ({
+				...need,
+				unavailable: !fresh.some((item) => item.id === need.connectionId && item.status === "active")
+			}));
+			if (getConnectionWait(wait.id)?.version !== wait.version) return false;
+			if (ready && wait.intent && wait.intent.validUntil > Date.now() && wait.intent.objectiveRevision === wait.objectiveRevision) return true;
+		} catch {}
+		if (getConnectionWait(wait.id)?.version === wait.version) {
+			updateConnectionWait({
+				...wait,
+				status: "open",
+				intent: void 0,
+				queuedInputId: void 0,
+				objectiveRevision: wait.objectiveRevision + 1
+			}, wait.version);
+			publishConnectionWait(input.sessionKey);
+		}
+		return false;
+	}
+	async act(sessionKey, action) {
+		const ownsLock = !this.busy.has(sessionKey);
+		if (!ownsLock && ![
+			"cancel",
+			"skip",
+			"replace_source"
+		].includes(action.action)) throw new Error("WAIT_CHANGED");
+		if (ownsLock) this.busy.add(sessionKey);
+		try {
+			const snapshot = this.snapshot(sessionKey);
+			let wait = getConnectionWait(action.waitId);
+			if (!wait || wait.sessionKey !== sessionKey || wait.principalId !== "local-owner" || wait.sessionId !== action.expectedSessionId || snapshot.sessionId !== action.expectedSessionId) throw new Error("SESSION_CHANGED");
+			if (wait.lastAction?.key === action.idempotencyKey && wait.lastAction.action === action.action) return { snapshot };
+			if (wait.status !== "open" || wait.version !== action.expectedVersion) throw new Error("WAIT_CHANGED");
+			wait = {
+				...wait,
+				lastAction: {
+					key: action.idempotencyKey,
+					action: action.action
+				}
+			};
+			if (action.action === "cancel") cancelConnectionObjective(sessionKey);
+			else if (action.action === "replace_source") {
+				const need = wait.needs.find((need) => need.key === action.needKey);
+				if (!need || !this.view(wait).needs.find((item) => item.key === need.key)?.alternatives?.some((item) => item.candidateRef === action.candidateRef)) throw new Error("Unsupported replacement.");
+				const replacement = resolveConnectionCandidate(action.candidateRef);
+				updateConnectionWait({
+					...wait,
+					summary: `${wait.summary}\nUse ${replacement.label} instead of ${need.label}, as confirmed by the user.`,
+					needs: wait.needs.map((item) => item.key === need.key ? replacement : item),
+					objectiveRevision: wait.objectiveRevision + 1,
+					intent: void 0
+				}, wait.version);
+			} else if (action.action === "skip") {
+				queueConnectionResolution({
+					...wait,
+					intent: void 0
+				}, "skipped");
+				this.deps.drain(sessionKey);
+			} else if (action.action === "connect") {
+				const need = wait.needs.find((need) => need.key === action.needKey);
+				if (!need) throw new Error("Unknown connection requirement.");
+				if (this.view(wait).needs.find((item) => item.key === need.key)?.phase === "blocked") throw new Error("Connector policy blocks this connection.");
+				const definition = getConnectorDefinition(need.connectorId);
+				if (definition?.runtime.type !== "composio" || definition.runtime.role !== "toolkit") throw new Error("Unsupported connector.");
+				const attemptId = randomUUID();
+				wait = updateConnectionWait({
+					...wait,
+					intent: {
+						objectiveRevision: wait.objectiveRevision,
+						validUntil: Date.now() + INTENT_TTL
+					},
+					needs: wait.needs.map((item) => item.key === need.key ? {
+						...item,
+						attempt: {
+							id: attemptId,
+							expiresAt: Date.now() + ATTEMPT_TTL
+						}
+					} : item)
+				}, wait.version);
+				publishConnectionWait(sessionKey);
+				const config = this.deps.getConfig();
+				if (!getConnectorInstance(config, need.connectorId)) await persistConfigMutation({
+					config,
+					mutate: () => installConnector(config, need.connectorId, {}),
+					save: () => this.deps.saveConfig(config)
+				});
+				const installationId = `${need.connectorId}-${wait.principalId}`;
+				if (!getConnectorInstallation(installationId)) upsertConnectorInstallation({
+					id: installationId,
+					connectorId: need.connectorId,
+					principalId: wait.principalId,
+					enabled: true,
+					allowedAgentIds: [],
+					maxScope: "read",
+					confirmationPolicy: "writes",
+					selectedConnectionIds: []
+				});
+				const auth = await this.adapter.authorize({
+					principalId: wait.principalId,
+					toolkit: definition.runtime.toolkit,
+					installationId,
+					authConfigId: getConfiguredComposioAuthConfigs(config, [definition.runtime.toolkit])?.[definition.runtime.toolkit]
+				});
+				const latest = getConnectionWait(wait.id);
+				if (!latest || latest.version !== wait.version || latest.status !== "open") throw new Error("WAIT_CHANGED");
+				updateConnectionWait({
+					...wait,
+					needs: wait.needs.map((item) => item.key === need.key ? {
+						...item,
+						attempt: {
+							id: attemptId,
+							connectionId: auth.connectionId,
+							expiresAt: Date.now() + ATTEMPT_TTL
+						}
+					} : item)
+				}, wait.version);
+				publishConnectionWait(sessionKey);
+				log.info({
+					sessionKey,
+					waitId: wait.id,
+					objectiveRevision: wait.objectiveRevision,
+					phase: "authorization_started"
+				}, "Connection authorization started");
+				return {
+					snapshot: this.snapshot(sessionKey),
+					authorizationUrl: auth.connectUrl
+				};
+			} else {
+				const fresh = await this.adapter.syncConnections({ principalId: wait.principalId });
+				const verified = new Set(fresh.filter((item) => item.status === "active").map((item) => item.id));
+				const latest = getConnectionWait(wait.id);
+				if (!latest || latest.version !== wait.version || latest.status !== "open") throw new Error("WAIT_CHANGED");
+				let needs = wait.needs.map((need) => {
+					const authorized = fresh.find((item) => item.providerConnectionId === need.attempt?.connectionId && item.status === "active");
+					return authorized ? {
+						...need,
+						unavailable: false,
+						...need.accountSelector && !need.accountId ? {} : {
+							connectionId: authorized.id,
+							accountId: authorized.accountId
+						},
+						attempt: void 0
+					} : {
+						...need,
+						unavailable: !fresh.some((item) => item.connectorId === need.connectorId && item.status === "active" && (!need.connectionId || item.id === need.connectionId) && (!need.accountId || item.accountId === need.accountId))
+					};
+				});
+				if (action.action === "select_account") {
+					const need = needs.find((item) => item.key === action.needKey);
+					const connection = fresh.find((item) => item.id === action.accountId && item.connectorId === need?.connectorId && item.status === "active");
+					if (!need || !connection || !this.view(wait, verified).needs.find((item) => item.key === need.key)?.accounts.some((item) => item.id === connection.id)) throw new Error("Account is unavailable.");
+					needs = needs.map((item) => item.key === need.key ? {
+						...item,
+						connectionId: connection.id,
+						accountId: connection.accountId,
+						unavailable: false
+					} : item);
+				}
+				needs = await this.checkCapabilities({
+					...wait,
+					needs
+				}, verified);
+				if (getConnectionWait(wait.id)?.version !== wait.version) throw new Error("WAIT_CHANGED");
+				const explicitContinue = action.action === "continue" || action.action === "confirm_scope";
+				wait = updateConnectionWait({
+					...wait,
+					needs,
+					...action.action === "confirm_scope" ? {
+						scopeConfirmedAt: Date.now(),
+						reviewRequired: false
+					} : {},
+					...needs.some((need) => need.capabilityError) ? { intent: void 0 } : explicitContinue ? { intent: {
+						objectiveRevision: wait.objectiveRevision,
+						validUntil: Date.now() + INTENT_TTL
+					} } : {}
+				}, wait.version);
+				const view = this.view(wait, verified);
+				if (view.phase === "ready" && wait.intent?.objectiveRevision === wait.objectiveRevision && wait.intent.validUntil > Date.now()) {
+					wait = queueConnectionResolution({
+						...wait,
+						needs: view.needs.map(({ phase: _phase, accounts: _accounts, reason: _reason, alternatives: _alternatives, ...need }) => need)
+					}, "continued");
+					log.info({
+						sessionKey,
+						waitId: wait.id,
+						objectiveRevision: wait.objectiveRevision,
+						phase: "resume_queued"
+					}, "Connection continuation queued");
+					this.deps.drain(sessionKey);
+				}
+			}
+			publishConnectionWait(sessionKey);
+			return { snapshot: this.snapshot(sessionKey) };
+		} catch (error) {
+			const wait = getActiveConnectionWait(sessionKey);
+			if (action.action === "connect" && wait?.status === "open" && wait.lastAction?.key === action.idempotencyKey) {
+				updateConnectionWait({
+					...wait,
+					intent: void 0,
+					needs: wait.needs.map((need) => need.key === action.needKey ? {
+						...need,
+						attempt: void 0
+					} : need)
+				}, wait.version);
+				publishConnectionWait(sessionKey);
+			}
+			throw error;
+		} finally {
+			if (ownsLock) this.busy.delete(sessionKey);
+		}
+	}
+};
+//#endregion
+export { ConnectionRecoveryService };

package/dist/src/connectors/health.js

@@ -1,6 +1,6 @@
-import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import { materializeConnectorMcpServer } from "./materialize.js";
 import { getConnectorInstance } from "./instances.js";
+import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import { listBundleMcpServerCapabilitiesForGateway } from "../agent/mcp/bundle-mcp-gateway.js";
 //#region src/connectors/health.ts
 function classifyConnectorHealthError(error) {

package/dist/src/connectors/learning-coordinator.d.ts

@@ -1,5 +1,4 @@
 import type { Config } from '../config/schema.js';
-import type { MemoryManager } from '../agent/memory/manager.js';
 import { type ConnectorLearningJob } from '../storage/sqlite/index.js';
 import { ComposioSessionsAdapter } from './composio-sessions.js';
 export type ConnectorLearningCoordinator = {
@@ -17,7 +16,6 @@ export type ConnectorLearningCoordinator = {
 export declare function startConnectorLearningCoordinator(options: {
     getConfig: () => Config;
     resolveAgentId: () => string;
-    getMemoryManager: () => MemoryManager;
     emit?: (type: string, payload: unknown) => void;
     intervalMs?: number;
     initialDelayMs?: number;

package/dist/src/connectors/learning-coordinator.js

@@ -9,13 +9,13 @@ import { connectorIdentityKey, normalizeConnectorIdentity } from "./connector-id
 import { ComposioSessionsAdapter } from "./composio-sessions.js";
 import { buildConnectorLearningArguments, getConnectorLearningPlan } from "./learning-recipes.js";
 import { getConnectorDefinition } from "./catalog.js";
-import { createUnderstandingSourceRun, getUnderstandingSourceGrant, listUnderstandingSourceRuns, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant } from "../user-context/sources/repository.js";
 import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import { ConnectedKnowledgePipeline } from "../knowledge/connected-knowledge-pipeline.js";
 import "../knowledge/index.js";
 import { ingestComposioConnectedSource } from "./connected-source-ingestion.js";
 import { deriveConnectedSourceUnderstanding } from "./connected-source-understanding.js";
 import { listConnectedContentCandidates, readConnectedContent } from "./content-enrichment.js";
+import { createUnderstandingSourceRun, getUnderstandingSourceGrant, listUnderstandingSourceRuns, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant } from "../user-context/sources/repository.js";
 //#region src/connectors/learning-coordinator.ts
 init_logger();
 const log = createLogger("ConnectorLearning");
@@ -59,7 +59,7 @@ function ensureUnderstandingSourceRun(job, toolkit, displayName) {
 	});
 }
 function learningEnabled(config) {
-	return config.userContext.enabled && config.userContext.understanding.enabled;
+	return config.userContext.enabled && config.userContext.userModel.enabled;
 }
 function startConnectorLearningCoordinator(options) {
 	const intervalMs = Math.max(2e3, Math.min(options.intervalMs ?? 1e4, 6e4));
@@ -209,7 +209,7 @@ function startConnectorLearningCoordinator(options) {
 		publish(updateConnectorLearningJob(job.id, { phase: "deriving" }));
 		let semantic = {
 			created: 0,
-			focusCount: 0,
+			knowledgeCount: 0,
 			status: "completed"
 		};
 		try {
@@ -218,14 +218,13 @@ function startConnectorLearningCoordinator(options) {
 				agentId: job.agentId,
 				sourceInstanceId: job.sourceInstanceId,
 				sourceRunId: sourceRun.id,
-				processingPolicy: getUnderstandingSourceGrant(sourceRun.grantId)?.processingPolicy ?? "local_only",
-				memoryManager: options.getMemoryManager()
+				processingPolicy: getUnderstandingSourceGrant(sourceRun.grantId)?.processingPolicy ?? "local_only"
 			});
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
 			semantic = {
 				created: 0,
-				focusCount: 0,
+				knowledgeCount: 0,
 				status: "failed",
 				error: CONNECTED_SOURCE_ANALYSIS_FAILED
 			};
@@ -235,7 +234,7 @@ function startConnectorLearningCoordinator(options) {
 				connectorId: job.connectorId
 			}, `Connected source semantic analysis failed: ${errorMessage}`);
 		}
-		const candidatesCreated = semantic.created + semantic.focusCount;
+		const candidatesCreated = semantic.created + semantic.knowledgeCount;
 		const incomplete = enrichmentErrors.length > 0 || semantic.status !== "completed";
 		const completed = updateConnectorLearningJob(job.id, {
 			status: "completed",

package/dist/src/connectors/principal.d.ts

@@ -0,0 +1,5 @@
+export declare function connectorPrincipalForSession(sessionKey: string | undefined): {
+    principalId: string;
+    agentId?: string;
+    isLocalOwner: boolean;
+};

package/dist/src/connectors/principal.js

@@ -0,0 +1,18 @@
+import { init_session_key, parseSessionKey } from "../routing/session-key.js";
+//#region src/connectors/principal.ts
+init_session_key();
+function connectorPrincipalForSession(sessionKey) {
+	const parsed = parseSessionKey(sessionKey);
+	if (!parsed || parsed.source === "cli" || parsed.source === "webchat") return {
+		principalId: "local-owner",
+		agentId: parsed?.agentId,
+		isLocalOwner: true
+	};
+	return {
+		principalId: `channel:${parsed.source}:${parsed.accountId}:${parsed.peerKind}:${parsed.peerId}`,
+		agentId: parsed.agentId,
+		isLocalOwner: false
+	};
+}
+//#endregion
+export { connectorPrincipalForSession };

package/dist/src/gateway/agent-builtin-tools.d.ts

@@ -61,10 +61,10 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "查看当前会话状态和用量。";
     };
 }, {
-    readonly id: "dreaming";
+    readonly id: "memory_maintenance";
     readonly description: {
-        readonly en: "Run configured background reflection and consolidation.";
-        readonly zh: "运行已配置的后台反思与信息整理。";
+        readonly en: "Inspect deterministic memory maintenance.";
+        readonly zh: "查看确定性的记忆整理任务。";
     };
 }, {
     readonly id: "tool_manual";
@@ -163,16 +163,34 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "将文本转换为语音音频。";
     };
 }, {
-    readonly id: "memory_search";
+    readonly id: "user_context_search";
     readonly description: {
-        readonly en: "Search long-term memory for relevant context.";
-        readonly zh: "在长期记忆中搜索相关上下文。";
+        readonly en: "Search typed user facts and preferences.";
+        readonly zh: "搜索结构化的用户事实与偏好。";
     };
 }, {
-    readonly id: "memory_get";
+    readonly id: "user_context_get";
     readonly description: {
-        readonly en: "Read a specific item from long-term memory.";
-        readonly zh: "读取一条指定的长期记忆。";
+        readonly en: "Read a typed user assertion.";
+        readonly zh: "读取一条结构化用户事实。";
+    };
+}, {
+    readonly id: "knowledge_search";
+    readonly description: {
+        readonly en: "Search scoped project and workspace knowledge.";
+        readonly zh: "搜索有作用域的项目与工作区知识。";
+    };
+}, {
+    readonly id: "knowledge_get";
+    readonly description: {
+        readonly en: "Read a scoped knowledge item.";
+        readonly zh: "读取一条有作用域的知识。";
+    };
+}, {
+    readonly id: "knowledge_write";
+    readonly description: {
+        readonly en: "Store a reviewable knowledge candidate.";
+        readonly zh: "保存一条可审查的知识候选。";
     };
 }, {
     readonly id: "session_search";
@@ -247,4 +265,4 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "使用已验证的参数执行选定的外部工具。";
     };
 }];
-export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "memory_search" | "memory_get" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "dreaming" | "web_extract" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "xopc_tool_search" | "xopc_tool_describe" | "xopc_tool_execute" | "send_message" | "send_media" | "read_media" | "create_share" | "session_status" | "tool_manual" | "delegate_task" | "skill_install" | "text_to_speech" | "execute_code" | "create_desktop_pet")[];
+export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "web_extract" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "xopc_tool_search" | "xopc_tool_describe" | "xopc_tool_execute" | "user_context_search" | "user_context_get" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "send_message" | "send_media" | "read_media" | "create_share" | "session_status" | "memory_maintenance" | "tool_manual" | "delegate_task" | "skill_install" | "text_to_speech" | "execute_code" | "create_desktop_pet")[];