@xopcai/xopc 0.0.382 → 0.0.384

package/dist/src/agent-matching/service.js

@@ -0,0 +1,192 @@
+import { normalizeSpecialistRequirements } from "../../packages/gateway-contract/src/specialists.js";
+import { resolveEffectiveAgentConfig } from "../agent-config/resolver.js";
+import { init_agent_config } from "../agent-config/index.js";
+import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
+import { getAvailablePersonalAgentTools, personalAgentModelAvailability } from "../personal-agent/specialist-capabilities.js";
+//#region src/agent-matching/service.ts
+init_repository();
+init_agent_config();
+const MATCHER_VERSION = 1;
+function assessSpecialist(agentId, input, context) {
+	const requirements = normalizeSpecialistRequirements(input);
+	const repository = new AgentCatalogRepository();
+	const agent = repository.get(agentId);
+	const checks = [];
+	const add = (condition, state, reasonCode, detail) => checks.push({
+		condition,
+		state,
+		reasonCode,
+		...detail ? { detail } : {}
+	});
+	const identityValid = agent && agent.enabled !== false && agent.provisioningState === "ready" && agent.purpose !== "task_dispatcher" && agent.id !== context.ownAgentId && !agent.id.startsWith("personal-");
+	add("identity", identityValid ? "verified" : "blocked", identityValid ? "agent_ready" : "agent_unavailable");
+	if (requirements.requestedAgentId && requirements.requestedAgentId !== agentId) add("requestedAgent", "blocked", "requested_agent_mismatch");
+	const entry = agent ? (({ revision: _revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...value }) => value)(agent) : void 0;
+	const config = entry ? resolveEffectiveAgentConfig({
+		defaults: repository.getSettings().defaults,
+		agent: entry
+	}).config : void 0;
+	const model = config ? personalAgentModelAvailability(config) : {
+		available: false,
+		reason: "Agent unavailable"
+	};
+	add("model", model.available ? "configured" : "blocked", model.available ? "provider_configured_network_unverified" : "model_unavailable", model.reason);
+	const availableTools = config ? getAvailablePersonalAgentTools(config, context) : [];
+	for (const tool of requirements.requiredTools ?? []) {
+		if (!identityValid) {
+			add(`tool:${tool}`, "blocked", "agent_unavailable");
+			continue;
+		}
+		if (!(config && config.tools[tool]?.mode !== "deny" && (!config.toolAllowlist || config.toolAllowlist.includes(tool)))) add(`tool:${tool}`, "blocked", "tool_unavailable");
+		else {
+			let check;
+			try {
+				check = context.getAgentToolAvailability?.(agentId, tool);
+			} catch {
+				check = {
+					condition: `tool:${tool}`,
+					state: "unknown",
+					reasonCode: "tool_verification_failed"
+				};
+			}
+			check ??= context.legacyToolPolicyOnly ? {
+				condition: `tool:${tool}`,
+				state: availableTools.includes(tool) ? "configured" : "blocked",
+				reasonCode: "legacy_tool_policy_only"
+			} : {
+				condition: `tool:${tool}`,
+				state: "unknown",
+				reasonCode: "tool_configured_registration_unverified"
+			};
+			checks.push(check);
+			if (check.state === "verified" && !availableTools.includes(tool)) availableTools.push(tool);
+		}
+	}
+	const verifiedSkills = [];
+	if (requirements.requiredSkills?.length) {
+		let skills;
+		try {
+			skills = identityValid ? context.getAgentSkillAvailability?.(agentId).skills : void 0;
+		} catch {}
+		for (const name of requirements.requiredSkills) {
+			const skill = skills?.find((item) => item.name.toLowerCase() === name);
+			if (skill?.availableForCurrentAgent) {
+				verifiedSkills.push(skill.name);
+				add(`skill:${name}`, "verified", "skill_available");
+			} else add(`skill:${name}`, skills ? "blocked" : "unknown", skills ? "skill_unavailable" : "skill_verification_unavailable", skill?.unavailableReason ?? (skills ? "not-installed" : "Skill availability cannot be verified"));
+		}
+	}
+	if (requirements.connector) {
+		let check;
+		try {
+			check = identityValid ? context.checkConnector?.(agentId, requirements.connector) : void 0;
+		} catch {
+			check = {
+				condition: "connector",
+				state: "unknown",
+				reasonCode: "connector_verification_failed"
+			};
+		}
+		checks.push(check ?? {
+			condition: "connector",
+			state: "unknown",
+			reasonCode: "connector_verification_unavailable"
+		});
+	}
+	const matched = [];
+	const missing = [];
+	const profile = agent?.specialistProfile;
+	const tags = [
+		...requirements.domain ? [[
+			"domain",
+			requirements.domain,
+			profile?.domains
+		]] : [],
+		...requirements.taskType ? [[
+			"taskType",
+			requirements.taskType,
+			profile?.taskTypes
+		]] : [],
+		...(requirements.inputKinds ?? []).map((value) => [
+			"input",
+			value,
+			profile?.inputKinds
+		]),
+		...(requirements.outputKinds ?? []).map((value) => [
+			"output",
+			value,
+			profile?.outputKinds
+		])
+	];
+	for (const [kind, value, declared] of tags) (declared?.includes(value) ? matched : missing).push(`${kind}:${value}`);
+	return {
+		id: agentId,
+		revision: agent?.revision,
+		name: agent?.profile?.name ?? agentId,
+		description: (agent?.profile?.description ?? "").slice(0, 300),
+		profileSource: profile ? "declared" : "legacy",
+		...profile ? { specialistProfile: profile } : {},
+		availableTools,
+		model,
+		verifiedSkills,
+		eligibility: checks.some((check) => check.state === "blocked") ? "blocked" : checks.some((check) => check.state === "unknown") ? "needs_verification" : "eligible",
+		checks,
+		matched,
+		missing,
+		catalogRevision: repository.getRevision(),
+		checkedAt: Date.now(),
+		matcherVersion: 1
+	};
+}
+function matchSpecialists(input, context, options = {}) {
+	const requirements = normalizeSpecialistRequirements(input);
+	const repository = new AgentCatalogRepository();
+	const revision = repository.getRevision();
+	let offset = 0;
+	if (options.cursor) {
+		const match = /^(\d+):(\d+)$/.exec(options.cursor);
+		if (!match || Number(match[1]) !== revision) throw new Error("Specialist catalog changed; restart matching");
+		offset = Number(match[2]);
+		if (!Number.isSafeInteger(offset)) throw new Error("Invalid matching cursor");
+	}
+	const ids = requirements.requestedAgentId ? [requirements.requestedAgentId] : repository.list().filter((agent) => agent.purpose !== "task_dispatcher" && agent.id !== context.ownAgentId && !agent.id.startsWith("personal-")).map((agent) => agent.id);
+	const order = {
+		eligible: 0,
+		needs_verification: 1,
+		blocked: 2
+	};
+	const candidates = ids.map((id) => assessSpecialist(id, requirements, context)).sort((a, b) => order[a.eligibility] - order[b.eligibility] || Number(b.matched.some((tag) => tag.startsWith("taskType:"))) - Number(a.matched.some((tag) => tag.startsWith("taskType:"))) || Number(b.matched.some((tag) => tag.startsWith("domain:"))) - Number(a.matched.some((tag) => tag.startsWith("domain:"))) || a.id.localeCompare(b.id));
+	const limit = Math.max(1, Math.min(50, Math.floor(options.limit ?? 10)));
+	return {
+		matcherVersion: 1,
+		catalogRevision: revision,
+		checkedAt: Date.now(),
+		total: candidates.length,
+		candidates: candidates.slice(offset, offset + limit),
+		...offset + limit < candidates.length ? { nextCursor: `${revision}:${offset + limit}` } : {}
+	};
+}
+function listSpecialistSummaries(context) {
+	return matchSpecialists({
+		version: 1,
+		summary: "Specialist discovery"
+	}, context, { limit: 50 });
+}
+/** Cheap snapshot projection; configuration is not proof of runtime tool readiness. */
+function summarizeSpecialist(config, context) {
+	return {
+		id: config.id,
+		role: (config.profile?.description || config.profile?.name || config.id).slice(0, 80),
+		tools: getAvailablePersonalAgentTools(config, context),
+		available: personalAgentModelAvailability(config).available,
+		toolEvidence: "configured",
+		...config.specialistProfile ? {
+			domains: config.specialistProfile.domains,
+			taskTypes: config.specialistProfile.taskTypes,
+			outputKinds: config.specialistProfile.outputKinds,
+			specialties: config.specialistProfile.specialties.slice(0, 2)
+		} : { profileSource: "legacy" }
+	};
+}
+//#endregion
+export { MATCHER_VERSION, assessSpecialist, listSpecialistSummaries, matchSpecialists, summarizeSpecialist };

package/dist/src/automations/capabilities/write.d.ts

@@ -38,6 +38,8 @@ export declare const AutomationCreateCapabilityInputSchema: z.ZodObject<{
         kind: z.ZodLiteral<"task_command">;
         taskId: z.ZodString;
         command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"retry_allocation">;
+        }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"move">;
             phase: z.ZodEnum<{
                 backlog: "backlog";
@@ -162,8 +164,8 @@ export declare const AutomationCreateCapabilityInputSchema: z.ZodObject<{
     delivery: z.ZodDefault<z.ZodObject<{
         notificationPolicy: z.ZodDefault<z.ZodEnum<{
             attention: "attention";
-            all: "all";
             none: "none";
+            all: "all";
         }>>;
         destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             key: z.ZodString;
@@ -239,6 +241,8 @@ export declare const AutomationUpdatePatchSchema: z.ZodObject<{
         kind: z.ZodLiteral<"task_command">;
         taskId: z.ZodString;
         command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"retry_allocation">;
+        }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"move">;
             phase: z.ZodEnum<{
                 backlog: "backlog";
@@ -379,8 +383,8 @@ export declare const AutomationUpdatePatchSchema: z.ZodObject<{
     delivery: z.ZodOptional<z.ZodOptional<z.ZodObject<{
         notificationPolicy: z.ZodDefault<z.ZodEnum<{
             attention: "attention";
-            all: "all";
             none: "none";
+            all: "all";
         }>>;
         destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             key: z.ZodString;

package/dist/src/automations/domain/validation.d.ts

@@ -68,6 +68,8 @@ export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     kind: z.ZodLiteral<"task_command">;
     taskId: z.ZodString;
     command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"retry_allocation">;
+    }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"move">;
         phase: z.ZodEnum<{
             backlog: "backlog";
@@ -187,8 +189,8 @@ export declare const AutomationSafetyPolicySchema: z.ZodObject<{
 export declare const AutomationDeliveryPolicySchema: z.ZodObject<{
     notificationPolicy: z.ZodDefault<z.ZodEnum<{
         attention: "attention";
-        all: "all";
         none: "none";
+        all: "all";
     }>>;
     destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         key: z.ZodString;
@@ -289,6 +291,8 @@ export declare const AutomationSchema: z.ZodObject<{
         kind: z.ZodLiteral<"task_command">;
         taskId: z.ZodString;
         command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"retry_allocation">;
+        }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"move">;
             phase: z.ZodEnum<{
                 backlog: "backlog";
@@ -397,8 +401,8 @@ export declare const AutomationSchema: z.ZodObject<{
     delivery: z.ZodDefault<z.ZodObject<{
         notificationPolicy: z.ZodDefault<z.ZodEnum<{
             attention: "attention";
-            all: "all";
             none: "none";
+            all: "all";
         }>>;
         destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             key: z.ZodString;
@@ -489,6 +493,8 @@ export declare const CreateAutomationSchema: z.ZodObject<{
         kind: z.ZodLiteral<"task_command">;
         taskId: z.ZodString;
         command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"retry_allocation">;
+        }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"move">;
             phase: z.ZodEnum<{
                 backlog: "backlog";
@@ -612,8 +618,8 @@ export declare const CreateAutomationSchema: z.ZodObject<{
     delivery: z.ZodDefault<z.ZodObject<{
         notificationPolicy: z.ZodDefault<z.ZodEnum<{
             attention: "attention";
-            all: "all";
             none: "none";
+            all: "all";
         }>>;
         destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             key: z.ZodString;
@@ -716,6 +722,8 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
         kind: z.ZodLiteral<"task_command">;
         taskId: z.ZodString;
         command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"retry_allocation">;
+        }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"move">;
             phase: z.ZodEnum<{
                 backlog: "backlog";
@@ -865,8 +873,8 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
     delivery: z.ZodOptional<z.ZodOptional<z.ZodObject<{
         notificationPolicy: z.ZodDefault<z.ZodEnum<{
             attention: "attention";
-            all: "all";
             none: "none";
+            all: "all";
         }>>;
         destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             key: z.ZodString;

package/dist/src/automations/draft/automation-draft-validator.d.ts

@@ -12,7 +12,7 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
     automation: {
         name: string;
         delivery: {
-            notificationPolicy: "attention" | "all" | "none";
+            notificationPolicy: "attention" | "none" | "all";
             destinations: ({
                 key: string;
                 kind: "gateway_event";
@@ -67,6 +67,8 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
             kind: "task_command";
             taskId: string;
             command?: {
+                type: "retry_allocation";
+            } | {
                 type: "move";
                 phase: "backlog" | "ready" | "active" | "review";
             } | {

package/dist/src/cli/commands/channels.js

@@ -1,8 +1,8 @@
 import { buildChannelCatalogForConfig } from "../../channels/catalog/channel-catalog-service.js";
 import { loadConfig, saveConfig } from "../../config/loader.js";
+import { formatExamples, register } from "../registry.js";
 import { listChannelPairingState } from "../../channels/pairing/pairing-service.js";
 import { approveChannelPairingFromCli } from "../../channels/pairing/approve-cli.js";
-import { formatExamples, register } from "../registry.js";
 import { colors } from "../utils/colors.js";
 import { Command } from "commander";
 //#region src/cli/commands/channels.ts

package/dist/src/cli/commands/connectors.js

@@ -1,8 +1,8 @@
 import { getStoreConnectorInstallPlan, installStoreConnector, listStoreConnectors } from "../../capabilities/store-connector.js";
 import { loadConfig, saveConfig } from "../../config/loader.js";
 import { register } from "../registry.js";
-import { confirm } from "@inquirer/prompts";
 import { Command } from "commander";
+import { confirm } from "@inquirer/prompts";
 //#region src/cli/commands/connectors.ts
 function parsePairs(values, option) {
 	const output = {};

package/dist/src/cli/commands/doctor/checks/database-schema.js

@@ -53,7 +53,7 @@ async function checkDatabaseSchema(ctx) {
 		id: "database-schema",
 		label: "Database schema",
 		status: "pass",
-		message: `SQLite schema v${status.dbVersion} (current release v246).`,
+		message: `SQLite schema v${status.dbVersion} (current release v249).`,
 		hints: []
 	};
 }

package/dist/src/cli/commands/extension-marketplace.js

@@ -16,8 +16,8 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import semver from "semver";
-import { confirm } from "@inquirer/prompts";
 import { Command } from "commander";
+import { confirm } from "@inquirer/prompts";
 //#region src/cli/commands/extension-marketplace.ts
 init_paths();
 const MANIFEST = "xopc.extension.json";

package/dist/src/cli/commands/models.js

@@ -16,8 +16,8 @@ import { prepareUpdateGlobalDefaults } from "../../gateway/global-defaults-admin
 import { disconnectProvider } from "../../providers/provider-disconnect.js";
 import { colors } from "../utils/colors.js";
 import { runCliOAuthLogin } from "../utils/oauth-login.js";
-import { input } from "@inquirer/prompts";
 import { Command } from "commander";
+import { input } from "@inquirer/prompts";
 //#region src/cli/commands/models.ts
 init_credentials();
 init_schema();

package/dist/src/cli/commands/onboard.js

@@ -11,8 +11,8 @@ import { initWorkspace } from "../utils/init-workspace.js";
 import { setupModel } from "./onboard/model.js";
 import { getChannelConfigurators } from "./onboard/channels/registry.js";
 import { setupChannels } from "./onboard/channels/index.js";
-import { select } from "@inquirer/prompts";
 import { Command } from "commander";
+import { select } from "@inquirer/prompts";
 //#region src/cli/commands/onboard.ts
 init_repository();
 init_schema();

package/dist/src/extensions/sdk/index.js

@@ -7,8 +7,8 @@ import { DEFAULT_SECURITY_CONFIG, checkExtensionDirSafety, checkExtensionPathSaf
 import { SlotRegistry, getSlotRegistry, registerSlotType } from "../slots.js";
 import { ExtensionDiagnostics, ExtensionLoaderCacheImpl, getExtensionCache, getExtensionDiagnostics } from "../diagnostics.js";
 import { ExtensionHookRunner, createHookContext, isHookEvent } from "../hooks.js";
-import { defineChannelPluginEntry } from "./channel-entry.js";
 import { registerExtensionCliProgram } from "./channel-helpers.js";
+import { defineChannelPluginEntry } from "./channel-entry.js";
 import { lazyFunction, lazyModule } from "./lazy.js";
 import { createMockExtensionApi, createTestGateway } from "./testing.js";
 //#region src/extensions/sdk/index.ts

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

@@ -277,4 +277,4 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "使用已验证的参数执行选定的外部工具。";
     };
 }];
-export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "user_context_search" | "user_context_get" | "user_context_update" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "xopc_tool_execute" | "web_extract" | "image_generate" | "read_media" | "xopc_tool_search" | "xopc_tool_describe" | "computer_use" | "send_message" | "text_to_speech" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "session_status" | "memory_maintenance" | "tool_manual" | "skill_install" | "send_media" | "create_share" | "delegate_task" | "execute_code" | "create_desktop_pet")[];
+export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "user_context_search" | "user_context_get" | "user_context_update" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "xopc_tool_execute" | "web_extract" | "read_media" | "xopc_tool_search" | "xopc_tool_describe" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "computer_use" | "send_message" | "text_to_speech" | "send_media" | "create_share" | "session_status" | "memory_maintenance" | "tool_manual" | "delegate_task" | "skill_install" | "execute_code" | "create_desktop_pet")[];

package/dist/src/gateway/agents-admin.d.ts

@@ -4,6 +4,7 @@
 import type { AgentEntry, AgentModelsOverride, EffectiveAgentConfig, SkillOverride } from '../agent-config/index.js';
 export type GatewayAgentRow = {
     id: string;
+    revision?: number;
     name?: string;
     description?: string;
     language?: string;
@@ -35,6 +36,7 @@ export type CreateAgentBody = {
     id?: string;
     workspace?: string;
     profile: NonNullable<AgentEntry['profile']>;
+    specialistProfile?: AgentEntry['specialistProfile'];
 };
 export type AgentAdminHttpStatus = 400 | 404 | 409;
 export type AgentAdminResult<T> = {
@@ -50,6 +52,8 @@ export declare function createGatewayAgent(body: CreateAgentBody): Promise<Agent
     workspace: string;
 }>>;
 export type UpdateAgentBody = {
+    expectedRevision?: number;
+    specialistProfile?: AgentEntry['specialistProfile'] | null;
     workspace?: string | null;
     profile?: AgentEntry['profile'] | null;
     models?: AgentModelsOverride | null;

package/dist/src/gateway/agents-admin.js

@@ -40,6 +40,7 @@ async function listGatewayAgents(_options = {}) {
 			...identity?.avatar ? { avatar: identity.avatar } : {},
 			workspace: profile.resolvedWorkspacePath,
 			profileDir: resolveAgentProfileDir(id),
+			revision: new AgentCatalogRepository().get(entry.id)?.revision,
 			override: structuredClone(entry),
 			effective: structuredClone(profile.config),
 			sources: { ...profile.sources },
@@ -98,7 +99,8 @@ async function createGatewayAgent(body) {
 			id: agentId,
 			enabled: true,
 			...workspace ? { workspace } : {},
-			profile: structuredClone(body.profile)
+			profile: structuredClone(body.profile),
+			...body.specialistProfile ? { specialistProfile: body.specialistProfile } : {}
 		});
 		return {
 			ok: true,
@@ -125,6 +127,7 @@ async function updateGatewayAgent(agentIdRaw, body) {
 	const patch = {};
 	if (body.workspace !== void 0) patch.workspace = body.workspace?.trim() ? resolveUserPath(body.workspace) : void 0;
 	if (body.profile !== void 0) patch.profile = body.profile ?? void 0;
+	if (body.specialistProfile !== void 0) patch.specialistProfile = body.specialistProfile ?? void 0;
 	if (body.models !== void 0) patch.models = body.models ?? void 0;
 	if (body.skills !== void 0) patch.skills = body.skills ?? void 0;
 	if (body.tools !== void 0) patch.tools = body.tools ?? void 0;
@@ -133,7 +136,7 @@ async function updateGatewayAgent(agentIdRaw, body) {
 	if (body.runtime !== void 0) patch.runtime = body.runtime ?? void 0;
 	try {
 		const service = new AgentCatalogService();
-		await service.update(agentId, patch);
+		await service.update(agentId, patch, body.expectedRevision);
 		if (body.setDefault === true) service.setDefault(agentId);
 		return {
 			ok: true,

package/dist/src/gateway/hono/routes/agents.js

@@ -16,17 +16,21 @@ function parseCreateAgentBody(raw) {
 	const allowedKeys = new Set([
 		"id",
 		"workspace",
-		"profile"
+		"profile",
+		"specialistProfile"
 	]);
 	const unknownKey = Object.keys(body).find((key) => !allowedKeys.has(key));
 	if (unknownKey) return { error: `unknown create-agent field "${unknownKey}"` };
 	const workspace = typeof body.workspace === "string" ? body.workspace : void 0;
 	const profile = AgentProfileSchema.safeParse(body.profile);
 	if (!profile.success) return { error: `profile ${profile.error.issues[0]?.message ?? "is required"}` };
+	const specialist = AgentEntrySchema.shape.specialistProfile.safeParse(body.specialistProfile);
+	if (!specialist.success) return { error: `specialistProfile ${specialist.error.issues[0]?.message ?? "is invalid"}` };
 	const id = typeof body.id === "string" ? body.id : void 0;
 	return {
 		workspace,
 		profile: profile.data,
+		...specialist.data ? { specialistProfile: specialist.data } : {},
 		...id !== void 0 ? { id } : {}
 	};
 }
@@ -101,6 +105,8 @@ function registerAgentsRoutes(authenticated, deps) {
 		}
 		const allowedPatchKeys = new Set([
 			"workspace",
+			"specialistProfile",
+			"expectedRevision",
 			"profile",
 			"models",
 			"skills",
@@ -115,6 +121,15 @@ function registerAgentsRoutes(authenticated, deps) {
 			ok: false,
 			error: { message: `unknown agent field "${unknownPatchKey}"` }
 		}, 400);
+		if (body.expectedRevision !== void 0 && (!Number.isInteger(body.expectedRevision) || Number(body.expectedRevision) < 1)) return c.json({
+			ok: false,
+			error: { message: "expectedRevision must be a positive integer" }
+		}, 400);
+		const specialistPatch = body.specialistProfile === null ? null : Object.hasOwn(body, "specialistProfile") ? AgentEntrySchema.shape.specialistProfile.safeParse(body.specialistProfile) : void 0;
+		if (specialistPatch && !specialistPatch.success) return c.json({
+			ok: false,
+			error: { message: `specialistProfile ${specialistPatch.error.issues[0]?.message ?? "is invalid"}` }
+		}, 400);
 		const skillsPatch = body.skills === null ? null : Object.hasOwn(body, "skills") ? SkillOverrideSchema.safeParse(body.skills) : void 0;
 		if (skillsPatch && skillsPatch !== null && !skillsPatch.success) return c.json({
 			ok: false,
@@ -166,6 +181,8 @@ function registerAgentsRoutes(authenticated, deps) {
 			error: { message: "workspace must be a string or null" }
 		}, 400);
 		const prep = await updateGatewayAgent(id, {
+			expectedRevision: body.expectedRevision,
+			...specialistPatch !== void 0 ? { specialistProfile: specialistPatch === null ? null : specialistPatch.data } : {},
 			...workspacePatch !== void 0 ? { workspace: workspacePatch } : {},
 			...profilePatch !== void 0 ? { profile: profilePatch === null ? null : profilePatch.data } : {},
 			...modelsPatch !== void 0 ? { models: modelsPatch } : {},

package/dist/src/gateway/hono/routes/lazy-bundles.js

@@ -3,6 +3,14 @@ function startsWithAny(path, prefixes) {
 	return prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
 }
 const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
+	{
+		id: "next-turn-suggestions",
+		match: (path) => /^\/api\/sessions\/[^/]+\/(?:next-turn-suggestion|next-turn-suggestion-feedback)$/.test(path),
+		load: async () => {
+			const { registerNextTurnSuggestionRoutes } = await import("./next-turn-suggestions.js");
+			return { register: registerNextTurnSuggestionRoutes };
+		}
+	},
 	{
 		id: "personal-agent",
 		match: (path) => startsWithAny(path, ["/api/personal-agent"]),

package/dist/src/gateway/hono/routes/next-turn-suggestions.d.ts

@@ -0,0 +1,3 @@
+import type { Hono } from 'hono';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function registerNextTurnSuggestionRoutes(app: Hono, deps: AuthenticatedRouteDeps): void;

package/dist/src/gateway/hono/routes/next-turn-suggestions.js

@@ -0,0 +1,39 @@
+import { nextTurnSuggestionFeedbackSchema } from "../../../../packages/gateway-contract/src/next-turn-suggestions.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
+import { getSessionMetadata } from "../../../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../../../storage/sqlite/session-repository.js";
+import { recordNextTurnSuggestionFeedback } from "../../../storage/sqlite/next-turn-suggestion-repository.js";
+import { createGatewayRouteLogger } from "../lib/route-logger.js";
+//#region src/gateway/hono/routes/next-turn-suggestions.ts
+init_src();
+init_session_repository();
+const log = createGatewayRouteLogger("NextTurnSuggestions");
+function registerNextTurnSuggestionRoutes(app, deps) {
+	app.get("/api/sessions/:key/next-turn-suggestion", (c) => {
+		c.header("Cache-Control", "no-store");
+		if (!deps.service.isGatewayReady()) return c.json({ status: "none" }, 503);
+		const conversationId = c.req.param("key");
+		if (!getSessionMetadata(conversationId)) return c.json({ error: "Session not found" }, 404);
+		const locale = c.req.query("locale") ?? "en";
+		if (locale !== "zh" && locale !== "en") return c.json({ error: "Invalid locale" }, 400);
+		try {
+			return c.json(deps.service.agentRunner.nextTurnSuggestions.get(conversationId, locale));
+		} catch (err) {
+			log.debug({
+				err,
+				conversationId
+			}, "Next turn suggestion unavailable");
+			return c.json({ status: "none" });
+		}
+	});
+	app.post("/api/sessions/:key/next-turn-suggestion-feedback", deps.strictRateLimitMiddleware, async (c) => {
+		if (!deps.service.isGatewayReady()) return c.json({ ok: false }, 503);
+		const conversationId = c.req.param("key");
+		if (!getSessionMetadata(conversationId)) return c.json({ error: "Session not found" }, 404);
+		const body = nextTurnSuggestionFeedbackSchema.safeParse(await c.req.json().catch(() => null));
+		if (!body.success) return c.json({ error: "Invalid feedback" }, 400);
+		return recordNextTurnSuggestionFeedback(conversationId, body.data) ? c.json({ ok: true }) : c.json({ error: "Suggestion not found" }, 404);
+	});
+}
+//#endregion
+export { registerNextTurnSuggestionRoutes };

package/dist/src/gateway/hono/routes/personal-agent.js

@@ -1,8 +1,8 @@
 import { getDevice, init_device_access_repository } from "../../../storage/sqlite/device-access-repository.js";
 import { getPersonalRequest, init_request_repository, listPersonalRequests } from "../../../personal-agent/request-repository.js";
 import { getPersonalAgent } from "../../../personal-agent/repository.js";
-import { writeAgentAvatarFromBase64 } from "../../agents-admin.js";
 import { TaskOriginRepository } from "../../../tasks/task-origin-repository.js";
+import { writeAgentAvatarFromBase64 } from "../../agents-admin.js";
 import { cancelPersonalRequest, personalRequestSnapshot, publishPersonalRequest } from "../../../personal-agent/request-service.js";
 import { PersonalOnboardingDraftSchema, PersonalOnboardingStepSchema, finishPersonalWelcome, getPersonalOnboarding, savePersonalOnboarding } from "../../../personal-agent/onboarding.js";
 import { PersonalAppearanceSchema, PersonalPreferencesSchema, createOrResumePersonalAgent, ensurePersonalConversationVisibility, listPersonalModels, patchPersonalProfile, refreshPersonalDelegationGuidance } from "../../../personal-agent/service.js";

package/dist/src/gateway/hono/routes/tasks.js

@@ -93,8 +93,9 @@ function registerTaskRoutes(authenticated, deps) {
 				ok: true,
 				task: created.model.task,
 				operationalState: created.model.operationalState,
+				allocation: created.model.allocation,
 				...created.runId ? { run: runs.get(created.runId) } : {}
-			}, created.runId ? 202 : 201);
+			}, created.runId || created.model.allocation ? 202 : 201);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			return c.json({

package/dist/src/gateway/next-turn-suggestions/generator.d.ts

@@ -0,0 +1,3 @@
+import type { SuggestionSnapshot } from './snapshot.js';
+export declare function parseSuggestionOutput(raw: string): string | null;
+export declare function generateNextTurnSuggestion(snapshot: SuggestionSnapshot, locale: 'zh' | 'en', modelRef: string, signal: AbortSignal): Promise<string | null>;