@xopcai/xopc 0.0.323 → 0.0.325

package/dist/src/agent/ipc/socket.js

@@ -15,7 +15,7 @@ var AgentSocketServer = class {
 	connections = /* @__PURE__ */ new Map();
 	messageHandler;
 	constructor(config, agentId) {
-		this.socketPath = resolveSocketPath(config, agentId);
+		this.socketPath = resolveSocketPath(agentId);
 	}
 	/**
 	* Start the socket server
@@ -143,7 +143,7 @@ var AgentSocketClient = class {
 	socketPath;
 	pendingResponses = /* @__PURE__ */ new Map();
 	constructor(config, targetAgentId) {
-		this.socketPath = resolveSocketPath(config, targetAgentId);
+		this.socketPath = resolveSocketPath(targetAgentId);
 	}
 	/**
 	* Connect to the socket server
@@ -255,7 +255,7 @@ var AgentSocketClient = class {
 	}
 };
 async function isSocketAvailable(config, agentId) {
-	const socketPath = resolveSocketPath(config, agentId);
+	const socketPath = resolveSocketPath(agentId);
 	return new Promise((resolve) => {
 		const socket = new Socket();
 		socket.on("connect", () => {

package/dist/src/agent/media-generation/runtime-shared.d.ts

@@ -90,7 +90,7 @@ export declare function throwCapabilityGenerationFailure(params: ThrowCapability
 export interface BuildNoCapabilityModelConfiguredMessageParams {
     /** Display label, e.g. "image-generation". */
     capabilityLabel: string;
-    /** Config key path, e.g. "agents.defaults.models.imageGeneration". */
+    /** Agent model capability key, e.g. "imageGeneration". */
     modelConfigKey: string;
     providers: ReadonlyArray<CapabilityProviderCandidate>;
     /** Optional env-var lookup, e.g. (id) => PROVIDER_ENV_MAP[id]. */

package/dist/src/agent/media-generation/runtime-shared.js

@@ -190,7 +190,7 @@ function throwCapabilityGenerationFailure(params) {
 	});
 }
 function buildNoCapabilityModelConfiguredMessage(params) {
-	const lines = [`No ${params.capabilityLabel} model configured. Set agents.defaults.models.${params.modelConfigKey} or pass modelOverride at call site.`];
+	const lines = [`No ${params.capabilityLabel} model configured. Configure ${params.modelConfigKey} in global Agent defaults or pass modelOverride at call site.`];
 	if (params.providers.length > 0) {
 		lines.push("Registered providers:");
 		for (const p of params.providers) {

package/dist/src/agent/memory/plugin-discovery.js

@@ -1,9 +1,8 @@
-import { discoverExtensionsFromDisk, init_discover_extensions } from "../../extensions/discover-extensions.js";
+import { discoverExtensionsFromDisk } from "../../extensions/discover-extensions.js";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { stat } from "node:fs/promises";
 //#region src/agent/memory/plugin-discovery.ts
-init_discover_extensions();
 async function discoverMemoryPlugins(config) {
 	const plugins = [];
 	for (const extension of discoverMemoryProviderExtensions(config)) for (const providerId of extension.manifest.contracts?.memoryProviders ?? []) plugins.push({

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

@@ -19,7 +19,7 @@ export declare class ModelManager {
     private currentProvider;
     private sessionModels;
     private fixedSessionModels;
-    /** Baseline model from `agents.list` / defaults merge when the session agent is created. */
+    /** Baseline model from the Agent catalog/defaults merge when the session Agent is created. */
     private sessionProfileDefaults;
     private sessionProfileFallbacks;
     constructor(config?: ModelManagerConfig);

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

@@ -16,7 +16,7 @@ var ModelManager = class {
 	currentProvider;
 	sessionModels = /* @__PURE__ */ new Map();
 	fixedSessionModels = /* @__PURE__ */ new Set();
-	/** Baseline model from `agents.list` / defaults merge when the session agent is created. */
+	/** Baseline model from the Agent catalog/defaults merge when the session Agent is created. */
 	sessionProfileDefaults = /* @__PURE__ */ new Map();
 	sessionProfileFallbacks = /* @__PURE__ */ new Map();
 	constructor(config = {}) {
@@ -30,7 +30,7 @@ var ModelManager = class {
 	*/
 	updateFromConfig(config) {
 		this.config = config;
-		const ref = getAgentDefaultModelRef(config);
+		const ref = getAgentDefaultModelRef();
 		this.defaultModel = ref ? ref : getDefaultModelSync(config);
 		this.sessionProfileDefaults.clear();
 		this.sessionProfileFallbacks.clear();

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.js

@@ -20,7 +20,7 @@ function isAgentTurnUnsettledError(err) {
 }
 function resolveAgentTurnTimeoutMs(config, conversationId) {
 	if (!config) return DEFAULT_AGENT_TURN_TIMEOUT_MS;
-	const configured = resolveEffectiveAgentConfigForSession(config, conversationId).config.runtime.timeoutMs;
+	const configured = resolveEffectiveAgentConfigForSession(conversationId).config.runtime.timeoutMs;
 	if (!configured) return DEFAULT_AGENT_TURN_TIMEOUT_MS;
 	return Math.min(MAX_AGENT_TURN_TIMEOUT_MS, Math.max(MIN_AGENT_TURN_TIMEOUT_MS, configured));
 }

package/dist/src/agent/prompt/response-language.js

@@ -1,9 +1,10 @@
 import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
 import { getSessionConfig } from "../../storage/sqlite/config-repository.js";
-import "../../storage/sqlite/index.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
 import { init_response_language, resolveResponseLanguage } from "../../i18n/response-language.js";
 //#region src/agent/prompt/response-language.ts
 init_response_language();
+init_sqlite();
 function resolveResponseLanguageForSession(config, conversationId) {
 	return resolveResponseLanguage(config?.userContext?.preferences?.responseLanguage ?? "auto", conversationId && isXopcDatabaseOpen() ? getSessionConfig(conversationId)?.responseLanguage : void 0);
 }

package/dist/src/agent/prompt/service-prompt-builder.js

@@ -1,11 +1,11 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
-import { buildInteractionStatePrompt } from "../../user-context/interaction-state.js";
+import { buildInteractionStatePrompt, init_interaction_state } from "../../user-context/interaction-state.js";
 import { getInteractionState } from "../../storage/sqlite/interaction-state-repository.js";
-import { DEFAULT_USER_TRUST_LEVEL } from "../../user-context/trust-policy.js";
+import { DEFAULT_USER_TRUST_LEVEL, init_trust_policy } from "../../user-context/trust-policy.js";
 import { getUserTrustPolicy } from "../../storage/sqlite/user-trust-repository.js";
-import "../../storage/sqlite/index.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
 import { appendStablePromptSection } from "./cache-boundary.js";
 import { getUserTimezone } from "../../user-model/repository.js";
 import "../../user-model/index.js";
@@ -15,6 +15,9 @@ import { resolveResponseLanguageForSession } from "./response-language.js";
 import { buildTtsSystemPromptHint } from "../../voice/tts/directives.js";
 import { mergeTtsConfigFromAppConfig } from "../../voice/tts/merge-config.js";
 //#region src/agent/prompt/service-prompt-builder.ts
+init_sqlite();
+init_interaction_state();
+init_trust_policy();
 init_logger();
 const log = createLogger("SystemPromptBuilder");
 var SystemPromptBuilder = class {

package/dist/src/agent/prompt/system-prompt.js

@@ -1,4 +1,4 @@
-import { buildActionTrustPrompt } from "../../user-context/trust-policy.js";
+import { buildActionTrustPrompt, init_trust_policy } from "../../user-context/trust-policy.js";
 import { PROMPT_CACHE_BOUNDARY, splitPromptCacheBoundary } from "./cache-boundary.js";
 import { buildAestheticSection, buildExecutionBiasSection, buildHumanCollaborationSection, buildProblemSolvingSection, buildSafetySection, buildToolCallStyleSection, buildWorkContinuitySection } from "./sections/behavior.js";
 import { buildExternalMemorySection, buildMemorySection, buildSkillsSection } from "./sections/memory-skills.js";
@@ -9,6 +9,7 @@ import { buildRuntimeSection, buildWorkspaceFilesIntroSection, buildWorkspaceSec
 import { buildResponseLanguageSection } from "./sections/response-language.js";
 import { buildOverridablePromptSection } from "./system-prompt-params.js";
 //#region src/agent/prompt/system-prompt.ts
+init_trust_policy();
 function joinSections(sections) {
 	return sections.filter((section) => Boolean(section?.trim())).join("\n\n");
 }

package/dist/src/agent/reply/post-compaction-context.js

@@ -73,12 +73,12 @@ function readPostCompactionContext(params) {
 	if (!cfg) return null;
 	let agentId = params.agentId;
 	if (!agentId && params.conversationId) try {
-		agentId = resolveEffectiveAgentProfileForSession(cfg, params.conversationId).agentId;
+		agentId = resolveEffectiveAgentProfileForSession(params.conversationId).agentId;
 	} catch {
 		return null;
 	}
 	if (!agentId) return null;
-	const resolved = resolve(join(resolveAgentProfileDir(cfg, agentId), "AGENTS.md"));
+	const resolved = resolve(join(resolveAgentProfileDir(agentId), "AGENTS.md"));
 	try {
 		return readPostCompactionContextFromAgentsMd(readFileSync(resolved, "utf-8"), {
 			cfg,

package/dist/src/agent/service/build-direct-message-content.js

@@ -6,7 +6,7 @@ init_schema();
 init_providers();
 async function buildDirectUserMessageContent(opts) {
 	const sk = opts.conversationId ?? "";
-	const modelRef = sk !== "" ? opts.modelManager.getModelForSession(sk) : getAgentDefaultModelRef(opts.config) ?? getDefaultModelSync(opts.config);
+	const modelRef = sk !== "" ? opts.modelManager.getModelForSession(sk) : getAgentDefaultModelRef() ?? getDefaultModelSync(opts.config);
 	return buildTranscriptUserMessage({
 		text: opts.content,
 		prepared: opts.attachments,

package/dist/src/agent/service/direct-turn-helpers.js

@@ -1,4 +1,4 @@
-import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
+import { getClarificationResumeInput, init_clarification_wait_repository } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput, init_connection_wait_repository } from "../../storage/sqlite/connection-wait-repository.js";
 import { resolveImageHandlingStrategy } from "../image/vision-detection.js";
 import { hydrateUserTurnForLlm } from "../inbound/attachment-pipeline.js";
@@ -21,6 +21,7 @@ import crypto from "node:crypto";
 * TTS, transcript persistence).
 */
 init_connection_wait_repository();
+init_clarification_wait_repository();
 /** Workspace + model + thinking level — common prep before any direct turn. */
 async function hydratePerTurnState(deps, conversationId, thinking) {
 	await deps.hydrateSessionWorkspaceFromStore(conversationId);

package/dist/src/agent/service/parse-outbound-session-key.js

@@ -1,7 +1,8 @@
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
-import "../../storage/sqlite/index.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
 import { INTERNAL_OUTBOUND_DROP_CHANNEL } from "../../channels/internal-outbound.js";
 //#region src/agent/service/parse-outbound-session-key.ts
+init_sqlite();
 /**
 * Map a session key to outbound channel routing (heartbeat/cron/virtual keys included).
 */

package/dist/src/agent/service/process-direct-streaming.js

@@ -1,6 +1,6 @@
 import { parseUserTurnDocument, renderUserTurnDocument } from "../../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
-import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
+import { getClarificationResumeInput, init_clarification_wait_repository } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput, init_connection_wait_repository } from "../../storage/sqlite/connection-wait-repository.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
 import { init_agent_session_key, resolveAgentMainConversationId } from "../../routing/agent-session-key.js";
@@ -25,6 +25,7 @@ init_agent_session_key();
 init_agent_scope();
 init_src();
 init_connection_wait_repository();
+init_clarification_wait_repository();
 const MAX_BUFFERED_STREAM_EVENTS = 512;
 const LOSSY_STREAM_EVENT_TYPES = new Set([
 	"message_update",
@@ -133,7 +134,7 @@ function pushAssistantReceipt(queue, text, runId, metadata) {
 	});
 }
 async function* runProcessDirectStreaming(deps, input) {
-	const conversationId = input.conversationId ?? resolveAgentMainConversationId({ agentId: resolveDefaultAgentId(deps.getConfig()) });
+	const conversationId = input.conversationId ?? resolveAgentMainConversationId({ agentId: resolveDefaultAgentId() });
 	const isConnectionResume = Boolean(input.runId && getConnectionResumeInput(conversationId, input.runId));
 	const isClarificationResume = Boolean(input.runId && getClarificationResumeInput(conversationId, input.runId));
 	const isInternalResume = isConnectionResume || isClarificationResume;

package/dist/src/agent/service/webchat-tts.js

@@ -1,5 +1,5 @@
 import { appendMediaToAssistantTranscriptEntry, findLatestAssistantTranscriptEntryId } from "../../storage/sqlite/transcript-repository.js";
-import "../../storage/sqlite/index.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
 import { isTTSAvailable } from "../../voice/tts/factory.js";
 import { speak } from "../../voice/tts/speak-core.js";
 import { mergeTtsConfigFromAppConfig } from "../../voice/tts/merge-config.js";
@@ -9,6 +9,7 @@ import { persistOutboundTtsAudio } from "../../channels/attachments/outbound-tts
 import "../../voice/tts/index.js";
 import { deleteMediaUris } from "../../media/session-references.js";
 //#region src/agent/service/webchat-tts.ts
+init_sqlite();
 /** True when the explicit TTS tool already produced durable Webchat audio. */
 function isSuccessfulWebchatTtsToolEvent(event) {
 	if (!event || typeof event !== "object" || Array.isArray(event)) return false;

package/dist/src/agent/service.d.ts

@@ -100,7 +100,7 @@ export declare class AgentService {
     /**
      * Apply config after save or hot reload so the default model updates without restarting the gateway.
      */
-    applyAgentDefaultsFromConfig(config: Config): void;
+    applyRuntimeConfiguration(config: Config): void;
     getSkillCatalog(): SkillCatalogEntry[];
     getSkillCatalogSnapshot(): SkillCatalogSnapshot;
     getAgentSkillAvailability(agentId: string): AgentSkillAvailabilityPayload;

package/dist/src/agent/service.js

@@ -1,13 +1,13 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
+import { init_attachment_ref, parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
+import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
+import { extractTextContent } from "./context/workspace.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
-import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
 import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { extractProfileAgentId } from "../config/agent-profile.js";
 import { init_providers, resolveModel } from "../providers/index.js";
-import { extractTextContent } from "./context/workspace.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";
 import { runWithEmbeddedExecutionSession } from "./embedded/execution-context.js";
@@ -74,6 +74,7 @@ import { readFile } from "node:fs/promises";
 init_agent_session_key();
 init_schema();
 init_logger();
+init_attachment_ref();
 init_agent_scope();
 init_providers();
 const log = createLogger("AgentService");
@@ -190,9 +191,8 @@ var AgentService = class {
 			const sk = update.conversationId?.trim();
 			if (sk) this.onSessionTranscriptUpdated?.(sk);
 		});
-		const appCfgForPaths = this.config.config;
-		if (!appCfgForPaths) throw new Error("AgentService requires config.config for session paths");
-		const defaultAgentHome = resolveAgentHomeDir(appCfgForPaths, resolveDefaultAgentId(appCfgForPaths));
+		if (!this.config.config) throw new Error("AgentService requires config.config for session paths");
+		const defaultAgentHome = resolveAgentHomeDir(resolveDefaultAgentId());
 		this.sessionConfigStore = new SessionConfigStore(defaultAgentHome);
 		this.hookRunner = this.createHookRunner();
 		this.hookHandler = new HookHandler({
@@ -243,6 +243,7 @@ var AgentService = class {
 			getChatPreviewService: config.getChatPreviewService,
 			dispatchTaskEvents: config.dispatchTaskEvents,
 			dispatchTaskRuns: config.dispatchTaskRuns,
+			onAgentCatalogMutate: config.onAgentCatalogMutate,
 			getWorkflowRunService: config.getWorkflowRunService,
 			onSkillsUpdated: config.onSkillsUpdated,
 			installSkillFromSource: (opts) => this.installSkillFromSource(opts),
@@ -287,7 +288,7 @@ var AgentService = class {
 			getThinkingDefault: () => void 0,
 			workspaceRoot: this.workspaceDir,
 			getWorkspaceRootForSession: (conversationId) => this.agentManager.getResolvedWorkspaceForSession(conversationId),
-			getAgentInternalStorageRootForSession: (conversationId) => resolveAgentHomeDir(this.config.config, extractProfileAgentId(conversationId, this.config.config)),
+			getAgentInternalStorageRootForSession: (conversationId) => resolveAgentHomeDir(extractProfileAgentId(conversationId)),
 			enqueueAutoTitle: (conversationId) => this.enqueueMaybeAutoTitleAfterPersist(conversationId),
 			onEmbeddedStreamEvent: (conversationId, event) => {
 				const ctx = this.sessionContextManager.getContext();
@@ -478,13 +479,13 @@ var AgentService = class {
 	/**
 	* Apply config after save or hot reload so the default model updates without restarting the gateway.
 	*/
-	applyAgentDefaultsFromConfig(config) {
+	applyRuntimeConfiguration(config) {
 		this.config.config = config;
 		this.sessionStore.updateConfig(config);
-		const ref = getAgentDefaultModelRef(config);
+		const ref = getAgentDefaultModelRef();
 		this.config.model = ref;
 		this.modelManager.updateFromConfig(config);
-		this.agentManager.updateAgentDefaults(config);
+		this.agentManager.updateRuntimeConfiguration(config);
 		this.commandHandler.updateAgentConfig(config);
 	}
 	getSkillCatalog() {
@@ -709,7 +710,7 @@ var AgentService = class {
 	enqueueMaybeAutoTitleAfterPersist(conversationId) {
 		(async () => {
 			try {
-				let modelRef = getAgentDefaultModelRef(this.config.config ?? {}) ?? this.config.model;
+				let modelRef = getAgentDefaultModelRef() ?? this.config.model;
 				if (!modelRef?.trim()) try {
 					modelRef = this.modelManager.getModelForSession(conversationId);
 				} catch {

package/dist/src/agent/service.types.d.ts

@@ -41,6 +41,8 @@ export interface AgentServiceConfig {
     getChatPreviewService?: () => ChatPreviewService | undefined;
     dispatchTaskEvents?: () => void;
     dispatchTaskRuns?: () => void;
+    /** Gateway: refresh runtime state and notify clients after a conversational Agent mutation. */
+    onAgentCatalogMutate?: () => void;
     /**
      * Gateway: reuse the gateway `SessionManager` store so web API and agent share one index + files.
      * When omitted, `AgentService` creates its own `SessionStore` (CLI / embedded).

package/dist/src/agent/session/session-inspector.js

@@ -24,9 +24,8 @@ var SessionInspector = class {
 	}
 	async ensureEffectiveSessionModel(conversationId) {
 		await this.opts.sessionHydrator.model(conversationId);
-		const cfg = this.opts.getConfig();
-		if (!cfg) return;
-		const profile = resolveEffectiveAgentProfileForSession(cfg, conversationId);
+		if (!this.opts.getConfig()) return;
+		const profile = resolveEffectiveAgentProfileForSession(conversationId);
 		const profileModelRef = profile.primaryModelRef?.trim();
 		if (profileModelRef) this.opts.modelManager.setSessionProfileDefault(conversationId, profileModelRef, profile.fallbacks);
 	}
@@ -58,7 +57,7 @@ var SessionInspector = class {
 	/** One-shot LLM answer for `/btw`: transcript as background, not persisted. */
 	btwQuery(conversationId, question, options) {
 		const config = this.opts.getConfig();
-		const profile = config ? resolveEffectiveAgentProfileForSession(config, conversationId) : void 0;
+		const profile = config ? resolveEffectiveAgentProfileForSession(conversationId) : void 0;
 		return runBtwQuery({
 			conversationId,
 			question,
@@ -104,7 +103,7 @@ var SessionInspector = class {
 		const model = this.opts.modelManager.getModelForSession(conversationId);
 		const workspace = effectiveWorkspacePathForSession(cfg, conversationId, await this.opts.sessionConfigStore.get(conversationId), getProjectForSession(conversationId));
 		const estTokens = await this.opts.sessionStore.estimateTokenUsage(conversationId, messages);
-		const profile = resolveEffectiveAgentProfileForSession(cfg, conversationId);
+		const profile = resolveEffectiveAgentProfileForSession(conversationId);
 		const deniedTools = [...profile.tools.denied].sort((a, b) => a.localeCompare(b));
 		const toolsSummary = deniedTools.length > 0 ? `denied: ${deniedTools.join(", ")}` : "(no denied tools)";
 		return formatSessionContextReport({

package/dist/src/agent/skills/marketplace/adapters/store/store-api-client.d.ts

@@ -12,6 +12,10 @@ import type { SkillMarkdownPreviewPayload } from '../../../types.js';
  * via `api.registerMarketplaceAdapter()`. Built-in values: 'store', 'skillhub', 'clawhub'.
  */
 export type SkillsMarketplaceProvider = string;
+export type MarketplaceSkillLocalizations = Partial<Record<'en' | 'zh-CN', {
+    displayName: string;
+    description: string;
+}>>;
 export interface SkillsStoreListParams {
     q?: string;
     page?: number;
@@ -31,6 +35,7 @@ export interface SkillsStorePackageListItem {
     name: string;
     type: string;
     description: string;
+    localizations?: MarketplaceSkillLocalizations;
     downloads: number;
     author: {
         username: string;

package/dist/src/agent/starter-agents.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from '../config/schema.js';
+import type { AgentEntry } from '../agent-config/index.js';
 export declare const STARTER_AGENTS_INITIALIZED_VERSION = 1;
 type StarterAgent = {
     id: string;
@@ -6,13 +6,12 @@ type StarterAgent = {
     description: string;
     role: string;
     emoji: string;
-    tools?: NonNullable<Config['agents']['list']>[number]['tools'];
+    tools?: AgentEntry['tools'];
     profileFiles: Record<string, string>;
 };
 export declare const STARTER_AGENTS: readonly StarterAgent[];
-export declare function materializeStarterAgentFiles(cfg: Config): void;
-export declare function ensureStarterAgentsInitialized(cfg: Config): {
-    config: Config;
+export declare function materializeStarterAgentFiles(): void;
+export declare function ensureStarterAgentsInitialized(): {
     changed: boolean;
 };
 export {};

package/dist/src/agent/starter-agents.js

@@ -1,9 +1,10 @@
-import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentProfileDir, resolveAgentWorkspaceDir } from "./agent-scope.js";
+import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
+import { init_agent_scope, resolveAgentProfileDir, resolveAgentWorkspaceDir } from "./agent-scope.js";
 import { WORKSPACE_FILES, init_paths } from "../config/paths.js";
-import { applyAgentConfig } from "../commands/agents.config.js";
 import { join } from "node:path";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 //#region src/agent/starter-agents.ts
+init_repository();
 init_paths();
 init_agent_scope();
 const STARTER_AGENTS_INITIALIZED_VERSION = 1;
@@ -136,36 +137,36 @@ function renderStarterProfileFile(starter, name, content) {
 	if (!legacyName || legacyName === starter.displayName) return content;
 	return content.replace(`# SOUL.md - ${legacyName}`, `# SOUL.md - ${starter.displayName}`).replace(`You are ${legacyName},`, `You are ${starter.displayName},`).replace(`# TOOLS.md - ${legacyName} Tool Policy`, `# TOOLS.md - ${starter.displayName} Tool Policy`);
 }
-function hasAgentEntry(cfg, agentId) {
-	const id = normalizeAgentId(agentId);
-	return listAgentEntries(cfg).some((entry) => normalizeAgentId(entry.id) === id);
-}
 function writeFileIfMissing(path, content) {
 	if (!existsSync(path)) writeFileSync(path, content, "utf-8");
 }
-function materializeStarterAgentFiles(cfg) {
+function materializeStarterAgentFiles() {
 	for (const starter of STARTER_AGENTS) {
-		const profileDir = resolveAgentProfileDir(cfg, starter.id);
-		const workspaceDir = resolveAgentWorkspaceDir(cfg, starter.id);
+		const profileDir = resolveAgentProfileDir(starter.id);
+		const workspaceDir = resolveAgentWorkspaceDir(starter.id);
 		mkdirSync(profileDir, { recursive: true });
 		mkdirSync(workspaceDir, { recursive: true });
 		for (const [name, content] of Object.entries(starter.profileFiles)) writeFileIfMissing(join(profileDir, name), renderStarterProfileFile(starter, name, content));
 	}
 }
-function ensureStarterAgentsInitialized(cfg) {
-	let next = cfg;
+function ensureStarterAgentsInitialized() {
+	const repository = new AgentCatalogRepository();
+	let changed = false;
+	materializeStarterAgentFiles();
 	for (const starter of STARTER_AGENTS) {
-		if (hasAgentEntry(next, starter.id)) continue;
-		next = applyAgentConfig(next, {
-			agentId: starter.id,
+		const existing = repository.get(starter.id);
+		if (existing) {
+			if (existing.provisioningState !== "ready") repository.markProvisioned(starter.id);
+			continue;
+		}
+		repository.create({
+			id: starter.id,
+			enabled: true,
 			...starter.tools ? { tools: starter.tools } : {}
-		});
+		}, { ready: true });
+		changed = true;
 	}
-	materializeStarterAgentFiles(next);
-	return {
-		config: next,
-		changed: next !== cfg
-	};
+	return { changed };
 }
 //#endregion
 export { STARTER_AGENTS, STARTER_AGENTS_INITIALIZED_VERSION, ensureStarterAgentsInitialized, materializeStarterAgentFiles };

package/dist/src/agent/tasks/task-judge-service.js

@@ -71,10 +71,10 @@ function codingCompletionEvidence(rows) {
 }
 function resolveJudgeModel(config, conversationId, runtimeModel) {
 	if (config) {
-		const profile = resolveEffectiveAgentProfileForSession(config, conversationId);
+		const profile = resolveEffectiveAgentProfileForSession(conversationId);
 		if (profile.primaryModelRef?.trim()) return profile.primaryModelRef.trim();
 	}
-	return runtimeModel?.trim() || (config ? getAgentDefaultModelRef(config) : void 0);
+	return runtimeModel?.trim() || (config ? getAgentDefaultModelRef() : void 0);
 }
 var TaskJudgeService = class {
 	#tasks = new TaskRepository();

package/dist/src/agent/tool-manuals/xopc-use.d.ts

@@ -1 +1 @@
-export declare const xopcUseManual = "# XOPC Use Tool Manual\n\n## Purpose\n\n`xopc_use` operates first-class XOPC product objects without editing SQLite or product files directly.\nLoad this manual before a non-trivial mutation.\n\n```json\n{\n  \"mode\": \"scene | project | automation | note | task | task_run | chat_preview | local_app | settings\",\n  \"command\": \"...\",\n  \"args\": {},\n  \"dryRun\": false\n}\n```\n\nSend one object command per call. Inspect the returned JSON `ok` field; a tool call can\ncomplete successfully while the product command returns `ok: false`.\n\n## Scene delegation\n\nUse mode `scene` only after the user explicitly delegates recurring or future work. Inspect\n`list` before `start`; configure an existing matching scene instead of creating a duplicate.\nConfirm the goal, source scope, timing, promised result, and read-only action boundary in ordinary\nlanguage. A scene prepares suggestions or drafts and never sends mail or performs external writes.\n\n## Object routing\n\n| Object | Tool |\n| --- | --- |\n| Scene and scene result | `xopc_use` mode `scene` |\n| Project, milestone, project update | `xopc_use` mode `project` |\n| Automation | `xopc_use` mode `automation` |\n| Task intent and lifecycle | `xopc_use` mode `task` |\n| Task execution attempt, receipt, events and waits | `xopc_use` mode `task_run` |\n| Note | `xopc_use` mode `note` |\n| Lightweight UI preview | `xopc_use` mode `chat_preview` |\n| Local app | `xopc_use` mode `local_app` |\n| Settings jump target | `xopc_use` mode `settings` |\n| Workflow run | dedicated `workflow` tool; pass `taskId` to link it to a Task |\n| Session, memory, skill, connected app or workspace file | its dedicated tool |\n\nDo not emulate Workflow APIs through `xopc_use`. A Task is durable intent;\na TaskRun is one execution attempt; a WorkflowRun is a procedure execution and may belong\nto a TaskRun. Never treat these three objects as interchangeable.\n\n## Reliable protocol\n\n1. Use `list` then `get` when an id is unknown.\n2. Read the current `version` before a Task mutation.\n3. Use `dryRun: true` for broad Project changes or uncertain mutations.\n4. Mutate once with the exact id and current concurrency token.\n5. Verify the returned object and preserve any \u201COpen in xopc\u201D delivery link.\n6. On a conflict, read again and reconsider the operation; do not blindly retry.\n\nTimestamps are Unix epoch milliseconds. Array fields are arrays of strings. Omission\npreserves a patchable field; an empty array intentionally clears it. Prefer explicit\n`projectId`, `taskId`, `runId`, `noteId`, and `localAppId` fields over `id`.\n\n## Scenes\n\nCommands: `templates`, `list`, `get`, `mail_accounts`, `mail_search`,\n`mail_sources`, `read_notes`, `preflight`, `start`, `configure`, `transition`,\n`check`, `notes`, `work_item`, `update_work_item`, `schedule`, `results`,\n`feedback`, `mark_read`, `diagnostics`, `get_preferences`, and `set_preferences`.\n\nThe built-in templates are `weekly-family-plan` and `mail-follow-up`, currently version\n`1.0.0`. Discover templates instead of guessing keys or versions. Timestamps are Unix epoch\nmilliseconds. Use `preflight` or `dryRun: true` before `start` when account or model readiness\nis uncertain.\n\n### Safe start protocol\n\n1. Call `list` and reuse a matching activation when one exists.\n2. Call `templates`; for mail, call `mail_accounts` and `mail_search` with the exact account.\n3. Explain the selected source and timing to the user before creating the scene.\n4. Call `preflight` with the complete start input.\n5. Call `start` with the same input and a stable `requestId` for retry safety.\n6. Add notes, a work item, or a schedule as required; then call `get` to verify the state.\n\nFamily plans use scope `{ \"kind\": \"personal\" }` and permissions with only\n`user_notes`. Mail follow-up uses one selected mail source in an objects scope and exactly one\nauthorized account. Never broaden either scope to make preflight pass.\n\n### Mutations and results\n\nRead the current activation `revision` before `configure` or `transition`. Read the current\nnotes, schedule, work-item, or feedback revision before changing that object. On a conflict,\nread again and reconsider; do not retry with a guessed revision.\n\n`check` queues work and does not mean a result already exists. Use a stable `requestId` and\ninspect `results` later. `no_change` intentionally creates no user-facing draft. A returned\ndraft is not a sent message. Use `diagnostics` for source, model, queue, or notification failures.\n\nScene preferences control checks and reminders globally for the current principal. Read them\nwith `get_preferences` before `set_preferences`; preserve fields the user did not ask to change.\n\n## Projects\n\nCommands: `list`, `get`, `create`, `update`, `resolve_workspace`,\n`list_milestones`, `create_milestone`, `update_milestone`, `list_updates`,\nand `create_update`.\n\nProject statuses: `planned`, `active`, `paused`, `completed`, `cancelled`,\n`archived`. Health values: `unknown`, `on_track`, `at_risk`, `off_track`.\n\nA Project defines bounded shared context for related work. Its durable planning fields are `outcome`,\n`successCriteria`, `scope`, `nonGoals`, `ownerId`, `targetAt`, and `health`.\nUse `brief` for a concise description and `instructions` for durable operating guidance.\n\n### Create\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"AI Product Research\",\n    \"outcome\": \"Choose a validated product direction\",\n    \"successCriteria\": [\"Ten customer interviews\", \"Decision recorded\"],\n    \"scope\": { \"market\": \"developer tools\" },\n    \"nonGoals\": [\"Build the production product\"],\n    \"health\": \"on_track\",\n    \"targetAt\": 1760000000000,\n    \"workspaceRoot\": \"/path/to/repo\"\n  }\n}\n```\n\n### Update\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"status\": \"active\",\n    \"health\": \"at_risk\",\n    \"successCriteria\": [\"Ten interviews\", \"Evidence-backed decision\"]\n  }\n}\n```\n\n### Resolve a workspace\n\nUse `autoCreate: false` for lookup. Set it to true only when creating a Project is authorized.\n\n```json\n{ \"mode\": \"project\", \"command\": \"resolve_workspace\", \"args\": { \"workspacePath\": \"/path/to/repo\", \"autoCreate\": false } }\n```\n\n### Milestones\n\nMilestone statuses: `planned`, `active`, `completed`, `cancelled`.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_milestone\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"title\": \"Finish discovery\",\n    \"status\": \"active\",\n    \"targetAt\": 1760000000000,\n    \"sortOrder\": 10\n  }\n}\n```\n\nUse `list_milestones` with `projectId`. Use `update_milestone` with both\n`projectId` and `milestoneId`. Milestone deletion is intentionally not exposed.\n\n### Immutable project updates\n\nProject updates are append-only progress snapshots. They also update Project health.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"health\": \"on_track\",\n    \"summary\": \"Discovery is complete\",\n    \"progress\": [\"Interviewed ten users\"],\n    \"risks\": [\"Pricing remains unvalidated\"],\n    \"nextSteps\": [\"Run pricing tests\"]\n  }\n}\n```\n\nUse `list_updates` with `projectId` and optional `limit`. Updates cannot be edited.\n\n## Automations\n\nCommands: `list`, `get`, `create`, `update`, `delete`, `run`, `pause`,\n`resume`, and `history`.\n\nAutomation `create` automatically uses the current session Project when `projectId` is\nomitted. An explicit `projectId` takes precedence and is validated before mutation. Use an\nexplicit id when creating for a Project other than the current session Project.\n\n### Create in the current Project\n\n`trigger` and `action` use the same shapes as the Automation product API.\n\n```json\n{\n  \"mode\": \"automation\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"Daily project review\",\n    \"trigger\": { \"kind\": \"schedule\", \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 9 * * 1-5\", \"tz\": \"Asia/Shanghai\" } },\n    \"action\": { \"kind\": \"agent\", \"instruction\": \"Review the current project and summarize risks.\" }\n  }\n}\n```\n\nTo override the inherited Project, add `\"projectId\": \"project_id\"` to `args`.\nThe create payload may also be nested under `args.automation`; top-level `args.projectId`\nhas precedence.\n\n### List and history\n\n`list` and unqualified `history` inherit the current session Project. Pass an explicit\n`projectId` to query another Project. Pass `automationId` to `history` for one Automation.\n\n### Update and operate\n\nUse `automationId` for `get`, `update`, `delete`, `run`, `pause`, and `resume`.\nFor `update`, patch fields may be direct args or nested under `args.patch`. Supplying a new\n`projectId` reassigns the Automation after validating the target Project.\n\n## Tasks\n\nCommands: `list`, `get`, `create`, `update_dependencies`, `add_context`,\n`remove_context`, `command`, and `delete`.\n\nTask phases are `backlog`, `ready`, `active`, `review`, and `closed`.\nOperational state is projected separately as `idle`, `queued`, `running`, `waiting`,\n`verifying`, `succeeded`, `failed`, or `cancelled`. Never send either value as a\nfree-form status update.\n\n`task.get` returns the Task, its projected `model`, dependencies, dependents, context,\nauthority grants, TaskRuns, receipts, and waits.\nThe projected model is the correct source for current operational state and attention items.\n\n`delete` permanently removes the Task and its contracts, waits, context links, TaskRuns,\nreceipts, and Task-owned execution records. It does not delete linked Sessions, workspace files,\nor external artifacts. Cancel an active TaskRun before deletion, and use `dryRun: true` when\nthe user's intent is ambiguous.\n\n```json\n{ \"mode\": \"task\", \"command\": \"delete\", \"args\": { \"taskId\": \"task_id\" }, \"dryRun\": true }\n```\n\n### Capture or start\n\n`createMode` defaults to `capture`, which creates a backlog Task without executing it.\nUse `start` only when immediate execution is intended.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"create\",\n  \"args\": {\n    \"objective\": \"Complete the customer research report\",\n    \"projectId\": \"project_id\",\n    \"createMode\": \"capture\",\n    \"priority\": \"high\",\n    \"expectedOutputs\": [\"Research report\"],\n    \"acceptanceCriteria\": [\"Sources are cited\"],\n    \"constraints\": [\"Do not contact customers without approval\"],\n    \"dependsOnTaskIds\": []\n  }\n}\n```\n\n### Dependencies\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"update_dependencies\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"dependsOnTaskIds\": [\"dependency_task_id\"]\n  }\n}\n```\n\n### Context links\n\nUse `add_context` to link a document, file, URL, session, memory, Task, artifact, or source\nas `input`, `reference`, `constraint`, `deliverable`, or `evidence` context.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"add_context\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"targetKind\": \"file\",\n    \"targetId\": \"/path/to/spec.md\",\n    \"role\": \"input\",\n    \"title\": \"Product specification\",\n    \"pinned\": true,\n    \"retrievalPolicy\": {},\n    \"metadata\": {}\n  }\n}\n```\n\nUse `remove_context` with `taskId` and the exact `edgeId` returned by `task.get`.\nDo not add authority grants through this tool; an Agent must not authorize itself.\n\n### Typed lifecycle commands\n\nEvery command requires `taskId`, the Task's current `expectedVersion`, a `type`, and\ntype-specific fields inside `commandArgs`.\n\nSupported command types:\n\n- `mark_ready`\n- `start`: `{ \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" } }`\n- `request_review`\n- `close`: `{ \"resolution\": \"done | cancelled | duplicate | wont_do\" }`\n- `reopen`: `{ \"phase\": \"ready | active\" }`\n- `add_wait`: `{ \"wait\": { \"kind\": \"dependency | approval | input | schedule | external | paused\", \"reason\": \"...\", \"condition\": {} } }`\n- `resolve_wait`: `{ \"waitId\": \"wait_id\", \"resolution\": {} }`\n- `delegate`: `{ \"agentId\": \"agent_id\" }`\n- `revise_contract`: `{ \"contract\": { ...complete contract... } }`\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"command\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"type\": \"start\",\n    \"commandArgs\": {\n      \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" }\n    }\n  }\n}\n```\n\nContract revision is replacement, not a patch. Read the Task and preserve all contract fields\nthe user did not ask to change. Resolve a wait through `resolve_wait`; do not directly mutate\na TaskRun or manufacture a phase transition.\n\n## TaskRuns\n\nTaskRun inspection is read-only except for explicit cancellation. Other execution state is\ncontrolled by Task commands and the runtime coordinator.\n\n### List attempts for a Task\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"list\", \"args\": { \"taskId\": \"task_id\", \"limit\": 20 } }\n```\n\nThe result contains run attempts, finalized receipts, and active waits.\n\n### Inspect one attempt\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"get\", \"args\": { \"runId\": \"run_id\" } }\n```\n\nThe result contains the TaskRun, its receipt when terminal, ordered events, and active Task waits.\n\n### Cancel an attempt\n\nRead the run first, then pass its current version. Cancellation creates a terminal receipt.\n\n```json\n{\n  \"mode\": \"task_run\",\n  \"command\": \"cancel\",\n  \"args\": { \"runId\": \"run_id\", \"expectedVersion\": 2, \"reason\": \"User cancelled execution\" }\n}\n```\n\nDo not guess commands such as retry, force-complete, heartbeat, or transition; they are not Agent APIs.\n\n## Notes\n\nCommands: `list`, `get`, `create`, `append`, `preview_edit`, `update`, and `delete`.\nUse Notes for durable prose and reference material, not as a Task substitute. Prefer `append`\nwhen preserving user content. Use `preview_edit` before a canonical rewrite.\n\n```json\n{ \"mode\": \"note\", \"command\": \"create\", \"args\": { \"title\": \"Decision\", \"markdown\": \"...\", \"projectId\": \"project_id\" } }\n```\n\n```json\n{ \"mode\": \"note\", \"command\": \"append\", \"args\": { \"noteId\": \"note_id\", \"heading\": \"AI synthesis\", \"content\": \"...\" } }\n```\n\nUse `update` with `status: \"trashed\"` for a recoverable removal. `delete` permanently\nremoves the Note and its stored snapshots and media; use `dryRun: true` first when the\nuser's intent is ambiguous.\n\n```json\n{ \"mode\": \"note\", \"command\": \"delete\", \"args\": { \"noteId\": \"note_id\" }, \"dryRun\": true }\n```\n\n## Chat previews, local apps, and settings\n\nUse `chat_preview` by default when the user asks to design, mock up, or quickly show a UI in\nthe current conversation. It creates no Project and no Local App. Commands are `create`,\n`get`, and `revise`. Source consists of `markup`, `styles`, and optional `script`;\ndo not include a full HTML document or remote dependencies. Revision requires the exact\n`baseRevision` returned by the prior call.\n\nUse `local_app` only when the user explicitly asks for a durable, installable app or chooses\n\u201CSave as app\u201D on a chat preview. Do not create a Local App merely to render a UI draft.\n\nLocal app commands are `list`, `get`, `create`, and `validate`. Installation,\nactivation, rollback, and uninstall remain product runtime operations.\n\nSettings supports only `open` and returns an exact product jump target without changing config.\n\n## Error recovery\n\n| Result | Recovery |\n| --- | --- |\n| service unavailable | Stop retrying and report the unavailable capability. |\n| not found | Re-list in the intended scope; do not invent another id. |\n| conflict | Read the current object and reassess using its latest version. |\n| waiting | Inspect the Task projection and TaskRun waits; resolve only the real blocker. |\n| invalid command or state | Read the object and use only a documented transition. |\n| unsupported operation | Use the dedicated tool or product UI; never write storage directly. |\n\n## Deliberate boundaries\n\n- Project deletion and milestone deletion are not Agent APIs.\n- TaskRun mutation is internal to execution coordination except for optimistic cancellation.\n- Project updates are immutable.\n- Workflow and Automation operations remain in their dedicated tools.\n- Only the documented Task and TaskRun commands are valid; do not infer hidden aliases.\n";
+export declare const xopcUseManual = "# XOPC Use Tool Manual\n\n## Purpose\n\n`xopc_use` operates first-class XOPC product objects without editing SQLite or product files directly.\nLoad this manual before a non-trivial mutation.\n\n```json\n{\n  \"mode\": \"agent | scene | project | automation | note | task | task_run | chat_preview | local_app | settings\",\n  \"command\": \"...\",\n  \"args\": {},\n  \"dryRun\": false\n}\n```\n\nSend one object command per call. Inspect the returned JSON `ok` field; a tool call can\ncomplete successfully while the product command returns `ok: false`.\n\n## Scene delegation\n\nUse mode `scene` only after the user explicitly delegates recurring or future work. Inspect\n`list` before `start`; configure an existing matching scene instead of creating a duplicate.\nConfirm the goal, source scope, timing, promised result, and read-only action boundary in ordinary\nlanguage. A scene prepares suggestions or drafts and never sends mail or performs external writes.\n\n## Object routing\n\n| Object | Tool |\n| --- | --- |\n| Agent definition and default Agent | `xopc_use` mode `agent` |\n| Scene and scene result | `xopc_use` mode `scene` |\n| Project, milestone, project update | `xopc_use` mode `project` |\n| Automation | `xopc_use` mode `automation` |\n| Task intent and lifecycle | `xopc_use` mode `task` |\n| Task execution attempt, receipt, events and waits | `xopc_use` mode `task_run` |\n| Note | `xopc_use` mode `note` |\n| Lightweight UI preview | `xopc_use` mode `chat_preview` |\n| Local app | `xopc_use` mode `local_app` |\n| Settings jump target | `xopc_use` mode `settings` |\n| Workflow run | dedicated `workflow` tool; pass `taskId` to link it to a Task |\n| Session, memory, skill, connected app or workspace file | its dedicated tool |\n\nDo not emulate Workflow APIs through `xopc_use`. A Task is durable intent;\na TaskRun is one execution attempt; a WorkflowRun is a procedure execution and may belong\nto a TaskRun. Never treat these three objects as interchangeable.\n\n## Agents\n\nCommands: `list`, `get`, `create`, `update`, `set_default`, `disable`,\n`delete`, and `purge`.\n\nAn Agent profile accepts only `name` and optional `instructions`. Put personality,\nlanguage, role, and behavioral guidance in `profile.instructions`; do not invent profile\nfields such as `description`, `language`, `emoji`, or `creature`.\n\n```json\n{\n  \"mode\": \"agent\",\n  \"command\": \"create\",\n  \"args\": {\n    \"id\": \"xiaomei\",\n    \"profile\": {\n      \"name\": \"\u5C0F\u7F8E\",\n      \"instructions\": \"\u4F7F\u7528\u4E2D\u6587\u4EA4\u6D41\uFF0C\u8BED\u6C14\u6E29\u67D4\u3001\u4EB2\u5207\u3001\u53EF\u7231\uFF0C\u540C\u65F6\u4FDD\u6301\u56DE\u7B54\u6E05\u6670\u53EF\u9760\u3002\"\n    },\n    \"idempotencyKey\": \"create-agent-xiaomei\"\n  }\n}\n```\n\nUse `list` before creating an Agent so an existing id is updated rather than duplicated.\nMutations other than `create` require the current `expectedRevision`; `set_default` uses\nthe catalog revision returned by `list`. `delete` preserves on-disk data, while `purge`\nalso removes it. Use `dryRun: true` to validate the exact same input contract without writing.\n\n## Reliable protocol\n\n1. Use `list` then `get` when an id is unknown.\n2. Read the current `version` before a Task mutation.\n3. Use `dryRun: true` for broad Project changes or uncertain mutations.\n4. Mutate once with the exact id and current concurrency token.\n5. Verify the returned object and preserve any \u201COpen in xopc\u201D delivery link.\n6. On a conflict, read again and reconsider the operation; do not blindly retry.\n\nTimestamps are Unix epoch milliseconds. Array fields are arrays of strings. Omission\npreserves a patchable field; an empty array intentionally clears it. Prefer explicit\n`projectId`, `taskId`, `runId`, `noteId`, and `localAppId` fields over `id`.\n\n## Scenes\n\nCommands: `templates`, `list`, `get`, `mail_accounts`, `mail_search`,\n`mail_sources`, `read_notes`, `preflight`, `start`, `configure`, `transition`,\n`check`, `notes`, `work_item`, `update_work_item`, `schedule`, `results`,\n`feedback`, `mark_read`, `diagnostics`, `get_preferences`, and `set_preferences`.\n\nThe built-in templates are `weekly-family-plan` and `mail-follow-up`, currently version\n`1.0.0`. Discover templates instead of guessing keys or versions. Timestamps are Unix epoch\nmilliseconds. Use `preflight` or `dryRun: true` before `start` when account or model readiness\nis uncertain.\n\n### Safe start protocol\n\n1. Call `list` and reuse a matching activation when one exists.\n2. Call `templates`; for mail, call `mail_accounts` and `mail_search` with the exact account.\n3. Explain the selected source and timing to the user before creating the scene.\n4. Call `preflight` with the complete start input.\n5. Call `start` with the same input and a stable `requestId` for retry safety.\n6. Add notes, a work item, or a schedule as required; then call `get` to verify the state.\n\nFamily plans use scope `{ \"kind\": \"personal\" }` and permissions with only\n`user_notes`. Mail follow-up uses one selected mail source in an objects scope and exactly one\nauthorized account. Never broaden either scope to make preflight pass.\n\n### Mutations and results\n\nRead the current activation `revision` before `configure` or `transition`. Read the current\nnotes, schedule, work-item, or feedback revision before changing that object. On a conflict,\nread again and reconsider; do not retry with a guessed revision.\n\n`check` queues work and does not mean a result already exists. Use a stable `requestId` and\ninspect `results` later. `no_change` intentionally creates no user-facing draft. A returned\ndraft is not a sent message. Use `diagnostics` for source, model, queue, or notification failures.\n\nScene preferences control checks and reminders globally for the current principal. Read them\nwith `get_preferences` before `set_preferences`; preserve fields the user did not ask to change.\n\n## Projects\n\nCommands: `list`, `get`, `create`, `update`, `resolve_workspace`,\n`list_milestones`, `create_milestone`, `update_milestone`, `list_updates`,\nand `create_update`.\n\nProject statuses: `planned`, `active`, `paused`, `completed`, `cancelled`,\n`archived`. Health values: `unknown`, `on_track`, `at_risk`, `off_track`.\n\nA Project defines bounded shared context for related work. Its durable planning fields are `outcome`,\n`successCriteria`, `scope`, `nonGoals`, `ownerId`, `targetAt`, and `health`.\nUse `brief` for a concise description and `instructions` for durable operating guidance.\n\n### Create\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"AI Product Research\",\n    \"outcome\": \"Choose a validated product direction\",\n    \"successCriteria\": [\"Ten customer interviews\", \"Decision recorded\"],\n    \"scope\": { \"market\": \"developer tools\" },\n    \"nonGoals\": [\"Build the production product\"],\n    \"health\": \"on_track\",\n    \"targetAt\": 1760000000000,\n    \"workspaceRoot\": \"/path/to/repo\"\n  }\n}\n```\n\n### Update\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"status\": \"active\",\n    \"health\": \"at_risk\",\n    \"successCriteria\": [\"Ten interviews\", \"Evidence-backed decision\"]\n  }\n}\n```\n\n### Resolve a workspace\n\nUse `autoCreate: false` for lookup. Set it to true only when creating a Project is authorized.\n\n```json\n{ \"mode\": \"project\", \"command\": \"resolve_workspace\", \"args\": { \"workspacePath\": \"/path/to/repo\", \"autoCreate\": false } }\n```\n\n### Milestones\n\nMilestone statuses: `planned`, `active`, `completed`, `cancelled`.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_milestone\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"title\": \"Finish discovery\",\n    \"status\": \"active\",\n    \"targetAt\": 1760000000000,\n    \"sortOrder\": 10\n  }\n}\n```\n\nUse `list_milestones` with `projectId`. Use `update_milestone` with both\n`projectId` and `milestoneId`. Milestone deletion is intentionally not exposed.\n\n### Immutable project updates\n\nProject updates are append-only progress snapshots. They also update Project health.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"health\": \"on_track\",\n    \"summary\": \"Discovery is complete\",\n    \"progress\": [\"Interviewed ten users\"],\n    \"risks\": [\"Pricing remains unvalidated\"],\n    \"nextSteps\": [\"Run pricing tests\"]\n  }\n}\n```\n\nUse `list_updates` with `projectId` and optional `limit`. Updates cannot be edited.\n\n## Automations\n\nCommands: `list`, `get`, `create`, `update`, `delete`, `run`, `pause`,\n`resume`, and `history`.\n\nAutomation `create` automatically uses the current session Project when `projectId` is\nomitted. An explicit `projectId` takes precedence and is validated before mutation. Use an\nexplicit id when creating for a Project other than the current session Project.\n\n### Create in the current Project\n\n`trigger` and `action` use the same shapes as the Automation product API.\n\n```json\n{\n  \"mode\": \"automation\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"Daily project review\",\n    \"trigger\": { \"kind\": \"schedule\", \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 9 * * 1-5\", \"tz\": \"Asia/Shanghai\" } },\n    \"action\": { \"kind\": \"agent\", \"instruction\": \"Review the current project and summarize risks.\" }\n  }\n}\n```\n\nTo override the inherited Project, add `\"projectId\": \"project_id\"` to `args`.\nThe create payload may also be nested under `args.automation`; top-level `args.projectId`\nhas precedence.\n\n### List and history\n\n`list` and unqualified `history` inherit the current session Project. Pass an explicit\n`projectId` to query another Project. Pass `automationId` to `history` for one Automation.\n\n### Update and operate\n\nUse `automationId` for `get`, `update`, `delete`, `run`, `pause`, and `resume`.\nFor `update`, patch fields may be direct args or nested under `args.patch`. Supplying a new\n`projectId` reassigns the Automation after validating the target Project.\n\n## Tasks\n\nCommands: `list`, `get`, `create`, `update_dependencies`, `add_context`,\n`remove_context`, `command`, and `delete`.\n\nTask phases are `backlog`, `ready`, `active`, `review`, and `closed`.\nOperational state is projected separately as `idle`, `queued`, `running`, `waiting`,\n`verifying`, `succeeded`, `failed`, or `cancelled`. Never send either value as a\nfree-form status update.\n\n`task.get` returns the Task, its projected `model`, dependencies, dependents, context,\nauthority grants, TaskRuns, receipts, and waits.\nThe projected model is the correct source for current operational state and attention items.\n\n`delete` permanently removes the Task and its contracts, waits, context links, TaskRuns,\nreceipts, and Task-owned execution records. It does not delete linked Sessions, workspace files,\nor external artifacts. Cancel an active TaskRun before deletion, and use `dryRun: true` when\nthe user's intent is ambiguous.\n\n```json\n{ \"mode\": \"task\", \"command\": \"delete\", \"args\": { \"taskId\": \"task_id\" }, \"dryRun\": true }\n```\n\n### Capture or start\n\n`createMode` defaults to `capture`, which creates a backlog Task without executing it.\nUse `start` only when immediate execution is intended.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"create\",\n  \"args\": {\n    \"objective\": \"Complete the customer research report\",\n    \"projectId\": \"project_id\",\n    \"createMode\": \"capture\",\n    \"priority\": \"high\",\n    \"expectedOutputs\": [\"Research report\"],\n    \"acceptanceCriteria\": [\"Sources are cited\"],\n    \"constraints\": [\"Do not contact customers without approval\"],\n    \"dependsOnTaskIds\": []\n  }\n}\n```\n\n### Dependencies\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"update_dependencies\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"dependsOnTaskIds\": [\"dependency_task_id\"]\n  }\n}\n```\n\n### Context links\n\nUse `add_context` to link a document, file, URL, session, memory, Task, artifact, or source\nas `input`, `reference`, `constraint`, `deliverable`, or `evidence` context.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"add_context\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"targetKind\": \"file\",\n    \"targetId\": \"/path/to/spec.md\",\n    \"role\": \"input\",\n    \"title\": \"Product specification\",\n    \"pinned\": true,\n    \"retrievalPolicy\": {},\n    \"metadata\": {}\n  }\n}\n```\n\nUse `remove_context` with `taskId` and the exact `edgeId` returned by `task.get`.\nDo not add authority grants through this tool; an Agent must not authorize itself.\n\n### Typed lifecycle commands\n\nEvery command requires `taskId`, the Task's current `expectedVersion`, a `type`, and\ntype-specific fields inside `commandArgs`.\n\nSupported command types:\n\n- `mark_ready`\n- `start`: `{ \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" } }`\n- `request_review`\n- `close`: `{ \"resolution\": \"done | cancelled | duplicate | wont_do\" }`\n- `reopen`: `{ \"phase\": \"ready | active\" }`\n- `add_wait`: `{ \"wait\": { \"kind\": \"dependency | approval | input | schedule | external | paused\", \"reason\": \"...\", \"condition\": {} } }`\n- `resolve_wait`: `{ \"waitId\": \"wait_id\", \"resolution\": {} }`\n- `delegate`: `{ \"agentId\": \"agent_id\" }`\n- `revise_contract`: `{ \"contract\": { ...complete contract... } }`\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"command\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"type\": \"start\",\n    \"commandArgs\": {\n      \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" }\n    }\n  }\n}\n```\n\nContract revision is replacement, not a patch. Read the Task and preserve all contract fields\nthe user did not ask to change. Resolve a wait through `resolve_wait`; do not directly mutate\na TaskRun or manufacture a phase transition.\n\n## TaskRuns\n\nTaskRun inspection is read-only except for explicit cancellation. Other execution state is\ncontrolled by Task commands and the runtime coordinator.\n\n### List attempts for a Task\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"list\", \"args\": { \"taskId\": \"task_id\", \"limit\": 20 } }\n```\n\nThe result contains run attempts, finalized receipts, and active waits.\n\n### Inspect one attempt\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"get\", \"args\": { \"runId\": \"run_id\" } }\n```\n\nThe result contains the TaskRun, its receipt when terminal, ordered events, and active Task waits.\n\n### Cancel an attempt\n\nRead the run first, then pass its current version. Cancellation creates a terminal receipt.\n\n```json\n{\n  \"mode\": \"task_run\",\n  \"command\": \"cancel\",\n  \"args\": { \"runId\": \"run_id\", \"expectedVersion\": 2, \"reason\": \"User cancelled execution\" }\n}\n```\n\nDo not guess commands such as retry, force-complete, heartbeat, or transition; they are not Agent APIs.\n\n## Notes\n\nCommands: `list`, `get`, `create`, `append`, `preview_edit`, `update`, and `delete`.\nUse Notes for durable prose and reference material, not as a Task substitute. Prefer `append`\nwhen preserving user content. Use `preview_edit` before a canonical rewrite.\n\n```json\n{ \"mode\": \"note\", \"command\": \"create\", \"args\": { \"title\": \"Decision\", \"markdown\": \"...\", \"projectId\": \"project_id\" } }\n```\n\n```json\n{ \"mode\": \"note\", \"command\": \"append\", \"args\": { \"noteId\": \"note_id\", \"heading\": \"AI synthesis\", \"content\": \"...\" } }\n```\n\nUse `update` with `status: \"trashed\"` for a recoverable removal. `delete` permanently\nremoves the Note and its stored snapshots and media; use `dryRun: true` first when the\nuser's intent is ambiguous.\n\n```json\n{ \"mode\": \"note\", \"command\": \"delete\", \"args\": { \"noteId\": \"note_id\" }, \"dryRun\": true }\n```\n\n## Chat previews, local apps, and settings\n\nUse `chat_preview` by default when the user asks to design, mock up, or quickly show a UI in\nthe current conversation. It creates no Project and no Local App. Commands are `create`,\n`get`, and `revise`. Source consists of `markup`, `styles`, and optional `script`;\ndo not include a full HTML document or remote dependencies. Revision requires the exact\n`baseRevision` returned by the prior call.\n\nUse `local_app` only when the user explicitly asks for a durable, installable app or chooses\n\u201CSave as app\u201D on a chat preview. Do not create a Local App merely to render a UI draft.\n\nLocal app commands are `list`, `get`, `create`, and `validate`. Installation,\nactivation, rollback, and uninstall remain product runtime operations.\n\nSettings supports only `open` and returns an exact product jump target without changing config.\n\n## Error recovery\n\n| Result | Recovery |\n| --- | --- |\n| service unavailable | Stop retrying and report the unavailable capability. |\n| not found | Re-list in the intended scope; do not invent another id. |\n| conflict | Read the current object and reassess using its latest version. |\n| waiting | Inspect the Task projection and TaskRun waits; resolve only the real blocker. |\n| invalid command or state | Read the object and use only a documented transition. |\n| unsupported operation | Use the dedicated tool or product UI; never write storage directly. |\n\n## Deliberate boundaries\n\n- Project deletion and milestone deletion are not Agent APIs.\n- TaskRun mutation is internal to execution coordination except for optimistic cancellation.\n- Project updates are immutable.\n- Workflow and Automation operations remain in their dedicated tools.\n- Only the documented Task and TaskRun commands are valid; do not infer hidden aliases.\n";