@xopcai/xopc 0.0.382 → 0.0.384

package/dist/src/agent/child-agent-factory.js

@@ -1,11 +1,17 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { cloudCreditBudgetStopMessage, isCloudCreditBudgetExhausted } from "../providers/xopc-cloud-credit-budget.js";
 import { evictEmbeddedSessionRunner } from "./embedded/session-runner.js";
 import { InMemoryTranscriptRuntime } from "./embedded/transcript-runtime.js";
 import { runXopcEmbeddedTurn } from "./embedded/run-turn.js";
 import { createAgentTurnPolicy } from "./orchestration/agent-turn-policy.js";
+import { createDelegationBudgetPolicy, resolveDelegationBudget } from "./orchestration/delegation-budget.js";
 import { buildSubagentSystemPrompt } from "./prompt/subagent-context.js";
 import { resolveResponseLanguageForSession } from "./prompt/response-language.js";
 import { randomUUID } from "node:crypto";
 //#region src/agent/child-agent-factory.ts
+init_logger();
+const log = createLogger("DelegateChild");
 /** Leaf workers use the same execution, transcript and verification harness as foreground turns. */
 function createDelegateChildHandle(options) {
 	const controller = new AbortController();
@@ -31,47 +37,43 @@ function createDelegateChildHandle(options) {
 				toolExecutorConfig: options.toolExecutorConfig,
 				browserConversationId: options.requesterConversationId ?? options.conversationId
 			}).filter((tool) => allow.has(tool.name));
-			const limit = Math.min(60, Math.max(1, Math.floor(options.maxIterations)));
-			let toolIterations = 0, exhausted = false, tokens = 0;
-			let terminationReason;
-			const policy = createAgentTurnPolicy({
-				maxTurns: limit + 1,
-				maxToolFailures: 5,
-				authorizeToolCall: async (context, signal) => {
-					const { toolCall } = context;
-					if (options.isComplete?.()) return {
-						block: true,
-						reason: "The delegated result is already complete."
-					};
-					if (!allow.has(toolCall.name)) return {
+			const budget = createDelegationBudgetPolicy(resolveDelegationBudget(options.budgetTier, options.maxIterations, options.timeoutMs), {
+				isComplete: options.isComplete,
+				authorizeToolCall: options.authorizeToolCall
+			});
+			const limit = budget.snapshot().limits.maxToolCalls;
+			let handoffCompleted = false;
+			const expanded = createAgentTurnPolicy({ authorizeToolCall: async (context, signal) => {
+				const { toolCall } = context;
+				const creditStop = cloudCreditBudgetStopMessage();
+				if (creditStop) {
+					budget.stop("credit_budget", creditStop);
+					return {
 						block: true,
-						reason: "Tool is outside the delegated capability set."
+						terminate: true,
+						reason: creditStop
 					};
-					if (toolIterations >= limit || tokens >= 1e5) {
-						exhausted = true;
-						return {
-							block: true,
-							terminate: true,
-							reason: "Sub-agent budget exhausted."
-						};
-					}
-					if (toolCall.name !== "data_batch") toolIterations++;
-					const decision = await options.authorizeToolCall?.(context, signal);
-					if (decision?.block) {
-						if (decision.terminate) {
-							exhausted = true;
-							terminationReason = decision.reason;
-						}
-						return decision;
-					}
 				}
-			});
-			const baseStop = policy.shouldStopAfterTurn;
-			policy.shouldStopAfterTurn = (context) => {
-				if (options.isComplete?.()) return true;
-				const stop = baseStop(context) || tokens >= 1e5;
-				if (stop) exhausted = true;
-				return stop;
+				if (!allow.has(toolCall.name)) return {
+					block: true,
+					reason: "Tool is outside the delegated capability set."
+				};
+				return budget.policy.beforeToolCall(context, signal);
+			} });
+			const policy = {
+				...budget.policy,
+				beforeToolCall: expanded.beforeToolCall,
+				beforeModelRequest: (signal) => {
+					const creditStop = cloudCreditBudgetStopMessage();
+					if (creditStop) budget.stop("credit_budget", creditStop);
+					if (controller.signal.aborted) budget.stop("cancelled", "Sub-agent cancelled");
+					return budget.policy.beforeModelRequest?.(signal);
+				},
+				shouldStopAfterTurn: (context) => {
+					const creditStop = cloudCreditBudgetStopMessage();
+					if (creditStop) budget.stop("credit_budget", creditStop);
+					return budget.policy.shouldStopAfterTurn(context);
+				}
 			};
 			try {
 				const result = await runXopcEmbeddedTurn({
@@ -89,7 +91,7 @@ function createDelegateChildHandle(options) {
 					transcriptRuntime: runtime,
 					turnPolicy: policy,
 					abortSignal: controller.signal,
-					timeoutMs: Math.min(options.timeoutMs ?? 3e5, 3e5),
+					timeoutMs: budget.snapshot().limits.timeoutMs,
 					thinkingLevel: "medium",
 					verifyChanges: options.verifyChanges,
 					systemPrompt: buildSubagentSystemPrompt({
@@ -98,12 +100,13 @@ function createDelegateChildHandle(options) {
 						workspace: options.workspace,
 						toolNames: tools.map((tool) => tool.name),
 						responseLanguage: resolveResponseLanguageForSession(options.getConfig(), options.requesterConversationId)
-					}),
+					}) + `\n\nDelegation budget: ${JSON.stringify(budget.snapshot().limits)}. Tokens are cumulative across requests. Search before reading targeted chunks; continue truncated reads from their returned next position. If asked for a budget handoff, stop tools and summarize evidence, incomplete work and precise next steps.`,
 					onEvent: (event) => {
 						const progress = options.progressHooks;
 						if (event.type === "message_end" && event.message.role === "assistant") {
 							const usage = event.message.usage;
-							tokens += usage?.totalTokens ?? (usage?.input ?? 0) + (usage?.output ?? 0);
+							budget.addTokens(usage?.totalTokens ?? (usage?.input ?? 0) + (usage?.output ?? 0));
+							if (budget.snapshot().handoffRequested && event.message.stopReason === "stop" && event.message.content.some((item) => item.type === "text" && item.text.trim()) && !event.message.content.some((item) => item.type === "toolCall")) handoffCompleted = true;
 						}
 						if (event.type === "tool_execution_start") progress?.onProgress({
 							type: "tool_start",
@@ -120,7 +123,7 @@ function createDelegateChildHandle(options) {
 							});
 							progress?.onProgress({
 								type: "iteration",
-								count: toolIterations,
+								count: budget.snapshot().usage.toolCalls,
 								max: limit
 							});
 						}
@@ -136,11 +139,45 @@ function createDelegateChildHandle(options) {
 				const verification = runtime.openSessionManager(options.workspace).getBranch().findLast((entry) => entry.type === "custom" && entry.customType === "coding_verification");
 				const proof = verification?.type === "custom" ? verification.data : void 0;
 				const unverified = options.verifyChanges && proof?.changed && (!proof.evidence.some((item) => item.kind === "check" && item.status === "passed") || proof.evidence.some((item) => item.status !== "passed"));
+				const snapshot = budget.snapshot();
+				const stopReason = controller.signal.aborted ? "cancelled" : isCloudCreditBudgetExhausted(result.errorMessage ?? "") ? "credit_budget" : /timed out|did not settle/i.test(result.errorMessage ?? "") ? "timeout" : snapshot.stopReason ?? (!result.ok ? "runtime_error" : unverified ? "verification" : "completed");
+				const messages = await runtime.loadMessages();
+				const evidence = stopReason !== "completed" && !handoffCompleted ? messages.filter((message) => message.role === "toolResult").slice(-3).map((message) => {
+					if (message.role !== "toolResult") return "";
+					const text = message.content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+					return `${message.toolName}: ${text.slice(0, 1500)}`;
+				}).join("\n\n") : "";
+				const summary = [
+					result.lastAssistantText,
+					result.errorMessage,
+					snapshot.stopMessage,
+					evidence ? `Recent tool evidence (bounded excerpts; not a completion claim):\n${evidence}` : "",
+					stopReason !== "completed" ? `Delegation stopped: ${stopReason}. Treat this as a partial handoff; validate completion before continuing.` : ""
+				].filter(Boolean).join("\n\n") || "(no final response)";
+				log.info({
+					conversationId,
+					stopReason,
+					budgetTier: snapshot.tier,
+					usage: snapshot.usage,
+					limits: snapshot.limits,
+					handoffRequested: snapshot.handoffRequested,
+					handoffCompleted
+				}, `Delegation stopped: ${stopReason}`);
 				return {
-					summary: [result.lastAssistantText || result.errorMessage, terminationReason].filter(Boolean).join("\n\n") || (exhausted ? "Sub-agent budget exhausted." : "(no final response)"),
-					toolIterations,
-					messages: await runtime.loadMessages(),
-					status: controller.signal.aborted ? "cancelled" : !result.ok ? "failed" : exhausted || unverified ? "partial" : "success",
+					summary,
+					stopReason,
+					budget: {
+						...snapshot,
+						stopReason
+					},
+					handoff: {
+						requested: snapshot.handoffRequested,
+						completed: handoffCompleted,
+						summary
+					},
+					toolIterations: snapshot.usage.toolCalls,
+					messages,
+					status: controller.signal.aborted ? "cancelled" : !result.ok ? "failed" : stopReason !== "completed" ? "partial" : "success",
 					...verification?.type === "custom" ? { verification: verification.data } : {}
 				};
 			} finally {

package/dist/src/agent/context/execution-scope.js

@@ -2,9 +2,9 @@ import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
 import { TaskRepository, init_task_repository } from "../../tasks/task-repository.js";
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
+import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.js";
 import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
-import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.js";
 import { buildActiveProjectContextForPrompt } from "./project-context.js";
 //#region src/agent/context/execution-scope.ts
 init_sqlite();

package/dist/src/agent/context/project-context.js

@@ -6,8 +6,8 @@ import { listKnowledgeItems, searchKnowledgeItems } from "../../knowledge-memory
 import "../../knowledge-memory/index.js";
 import { ProjectStore } from "../../projects/project-store.js";
 import { getProjectForSession, getProjectWorkspacePathForSession } from "../../projects/workspace.js";
-import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.js";
+import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { LocalAppStore } from "../../local-apps/store.js";
 //#region src/agent/context/project-context.ts
 init_sqlite();

package/dist/src/agent/embedded/run-turn.js

@@ -507,6 +507,8 @@ async function runXopcEmbeddedTurnInner(params) {
 			};
 			effectiveSystemPrompt = getCurrentSystemPrompt(effectiveContext.messages);
 			effectiveTools = getCurrentTools(effectiveContext.messages);
+			const modelRequestStop = params.turnPolicy?.beforeModelRequest?.(options?.signal ?? runAbortSignal);
+			if (modelRequestStop) return createContextErrorStream(streamModel, modelRequestStop);
 			const promptCacheSnapshot = buildPromptCacheSnapshot({
 				model: streamModel,
 				systemPrompt: effectiveSystemPrompt,
@@ -663,6 +665,15 @@ async function runXopcEmbeddedTurnInner(params) {
 			}
 			policyStopped ||= params.turnPolicy?.shouldStopAfterTurn(context) ?? false;
 			if (policyStopped || connectionStopped || clarificationStopped) return { action: "end" };
+			const continuation = params.turnPolicy?.takeContinuationMessage?.();
+			if (continuation) {
+				session.agent.steer({
+					role: "user",
+					content: continuation,
+					timestamp: Date.now()
+				});
+				return { action: "continue" };
+			}
 			if (baseDecision && baseDecision.action === "continue") return { action: "continue" };
 		};
 		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {

package/dist/src/agent/embedded/session-tool-result-guard.js

@@ -1,8 +1,8 @@
 import { init_string_coerce, normalizeOptionalString } from "../../utils/string-coerce.js";
+import { emitSessionTranscriptUpdate } from "../../session/transcript-events.js";
 import { extractToolCallsFromAssistant, extractToolResultId } from "../transcript/tool-call-id.js";
 import { makeMissingToolResult, sanitizeToolCallInputs } from "../transcript/session-transcript-repair.js";
 import { boundedJsonUtf8Bytes, firstEnumerableOwnKeys, jsonUtf8BytesOrInfinity } from "../../infra/json-utf8-bytes.js";
-import { emitSessionTranscriptUpdate } from "../../session/transcript-events.js";
 import { formatContextLimitTruncationNotice } from "./tool-result-context-guard.js";
 import { resolveLiveToolResultMaxChars, truncateToolResultMessage } from "./tool-result-truncation.js";
 //#region src/agent/embedded/session-tool-result-guard.ts

package/dist/src/agent/orchestration/agent-turn-policy.d.ts

@@ -4,6 +4,10 @@ export interface AgentTurnPolicy {
     beforeToolCall(context: BeforeToolCallContext, signal?: AbortSignal): Promise<BeforeToolCallResult | undefined>;
     afterToolCall(context: AfterToolCallContext): Promise<undefined>;
     shouldStopAfterTurn(context: AgentTurnContext): boolean;
+    /** One bounded continuation requested by a policy, e.g. a budget handoff. */
+    takeContinuationMessage?(): string | undefined;
+    /** Recheck limits at dispatch, including requests made by recovery paths. */
+    beforeModelRequest?(signal?: AbortSignal): string | undefined;
 }
 export interface AgentTurnPolicyOptions {
     maxTurns?: number;

package/dist/src/agent/orchestration/delegation-budget.d.ts

@@ -0,0 +1,60 @@
+import type { AgentTurnPolicy, AgentTurnPolicyOptions } from './agent-turn-policy.js';
+export declare const DELEGATION_BUDGETS: {
+    readonly light: {
+        readonly maxToolCalls: 15;
+        readonly maxTotalTokens: 50000;
+        readonly timeoutMs: 120000;
+    };
+    readonly standard: {
+        readonly maxToolCalls: 30;
+        readonly maxTotalTokens: 100000;
+        readonly timeoutMs: 300000;
+    };
+    readonly deep: {
+        readonly maxToolCalls: 60;
+        readonly maxTotalTokens: 200000;
+        readonly timeoutMs: 600000;
+    };
+};
+export type DelegationBudgetTier = keyof typeof DELEGATION_BUDGETS;
+export type DelegationStopReason = 'completed' | 'tool_calls' | 'total_tokens' | 'model_turns' | 'tool_failures' | 'timeout' | 'cancelled' | 'parent_policy' | 'credit_budget' | 'runtime_error' | 'verification';
+export declare function resolveDelegationBudget(tier?: DelegationBudgetTier, maxIterations?: number, timeoutMs?: number): {
+    tier: "light" | "standard" | "deep";
+    limits: {
+        maxToolCalls: number;
+        maxTotalTokens: 50000 | 100000 | 200000;
+        maxModelTurns: number;
+        maxToolFailures: number;
+        timeoutMs: number;
+    };
+};
+/** Reserve the last 20% for one tool-free handoff, without bypassing hard limits. */
+export declare function createDelegationBudgetPolicy(budget: ReturnType<typeof resolveDelegationBudget>, options: {
+    isComplete?: () => boolean;
+    authorizeToolCall?: AgentTurnPolicyOptions['authorizeToolCall'];
+}, now?: () => number): {
+    policy: AgentTurnPolicy;
+    addTokens(tokens: number): void;
+    stop(reason: DelegationStopReason, message?: string): void;
+    snapshot(): {
+        usage: {
+            elapsedMs: number;
+            toolCalls: number;
+            totalTokens: number;
+            modelTurns: number;
+            toolFailures: number;
+        };
+        stopReason: DelegationStopReason;
+        stopMessage: string;
+        handoffRequested: boolean;
+        handoffReason: DelegationStopReason;
+        tier: "light" | "standard" | "deep";
+        limits: {
+            maxToolCalls: number;
+            maxTotalTokens: 50000 | 100000 | 200000;
+            maxModelTurns: number;
+            maxToolFailures: number;
+            timeoutMs: number;
+        };
+    };
+};

package/dist/src/agent/orchestration/delegation-budget.js

@@ -0,0 +1,154 @@
+//#region src/agent/orchestration/delegation-budget.ts
+const DELEGATION_BUDGETS = {
+	light: {
+		maxToolCalls: 15,
+		maxTotalTokens: 5e4,
+		timeoutMs: 12e4
+	},
+	standard: {
+		maxToolCalls: 30,
+		maxTotalTokens: 1e5,
+		timeoutMs: 3e5
+	},
+	deep: {
+		maxToolCalls: 60,
+		maxTotalTokens: 2e5,
+		timeoutMs: 6e5
+	}
+};
+function resolveDelegationBudget(tier = "standard", maxIterations, timeoutMs) {
+	const preset = DELEGATION_BUDGETS[tier];
+	return {
+		tier,
+		limits: {
+			maxToolCalls: Math.min(60, Math.max(1, Math.floor(maxIterations ?? preset.maxToolCalls))),
+			maxTotalTokens: preset.maxTotalTokens,
+			maxModelTurns: Math.min(60, Math.max(1, Math.floor(maxIterations ?? preset.maxToolCalls))) + 1,
+			maxToolFailures: 5,
+			timeoutMs: Math.min(timeoutMs ?? preset.timeoutMs, preset.timeoutMs)
+		}
+	};
+}
+/** Reserve the last 20% for one tool-free handoff, without bypassing hard limits. */
+function createDelegationBudgetPolicy(budget, options, now = Date.now) {
+	const startedAt = now();
+	const usage = {
+		toolCalls: 0,
+		totalTokens: 0,
+		modelTurns: 0,
+		toolFailures: 0,
+		elapsedMs: 0
+	};
+	const limits = budget.limits;
+	let stopReason;
+	let stopMessage;
+	let handoffReason;
+	let handoffRequested = false;
+	let continuation;
+	let handoffRequestStarted = false;
+	const reasonAt = (ratio) => {
+		if (usage.totalTokens >= limits.maxTotalTokens * ratio) return "total_tokens";
+		if (now() - startedAt >= limits.timeoutMs * ratio) return "timeout";
+		if (usage.toolCalls >= limits.maxToolCalls * ratio) return "tool_calls";
+		if (usage.modelTurns >= limits.maxModelTurns * ratio) return "model_turns";
+		if (usage.toolFailures >= limits.maxToolFailures * ratio) return "tool_failures";
+	};
+	const handoff = () => `Delegation budget is approaching its ${handoffReason} limit. Do not call more tools. Return a concise handoff now: findings with file/line or source evidence, incomplete work, and precise next steps (including unread ranges). Do not claim the task is complete.`;
+	return {
+		policy: {
+			reset() {},
+			beforeModelRequest(signal) {
+				signal?.throwIfAborted();
+				const hard = reasonAt(1);
+				if (hard || stopReason) {
+					stopReason ??= hard;
+					return stopMessage ?? `Delegation stopped: ${stopReason}.`;
+				}
+				if (handoffRequested) {
+					if (handoffRequestStarted) {
+						stopReason = handoffReason;
+						return "Delegation handoff already attempted; no additional model request is permitted.";
+					}
+					handoffRequestStarted = true;
+				}
+			},
+			async beforeToolCall(context, signal) {
+				signal?.throwIfAborted();
+				if (options.isComplete?.()) return {
+					block: true,
+					reason: "The delegated result is already complete."
+				};
+				const hard = reasonAt(1);
+				if (hard) {
+					stopReason = hard;
+					return {
+						block: true,
+						terminate: true,
+						reason: `Sub-agent budget exhausted: ${hard}.`
+					};
+				}
+				if (handoffRequested) return {
+					block: true,
+					reason: handoff()
+				};
+				if (context.toolCall.name !== "data_batch") usage.toolCalls++;
+				const decision = await options.authorizeToolCall?.(context, signal);
+				if (decision?.block && decision.terminate) {
+					stopReason = "parent_policy";
+					stopMessage = decision.reason;
+				}
+				return decision;
+			},
+			async afterToolCall(context) {
+				if (context.isError) usage.toolFailures++;
+			},
+			shouldStopAfterTurn(context) {
+				usage.modelTurns++;
+				if (options.isComplete?.()) return true;
+				const hard = reasonAt(1);
+				if (hard || stopReason) {
+					stopReason ??= hard;
+					return true;
+				}
+				if (handoffRequested) {
+					stopReason = handoffReason;
+					return true;
+				}
+				const near = reasonAt(.8);
+				if (near && context.toolResults.length) {
+					handoffReason = near;
+					handoffRequested = true;
+					continuation = handoff();
+				}
+				return false;
+			},
+			takeContinuationMessage() {
+				const message = continuation;
+				continuation = void 0;
+				return message;
+			}
+		},
+		addTokens(tokens) {
+			usage.totalTokens += Math.max(0, tokens);
+		},
+		stop(reason, message) {
+			stopReason = reason;
+			stopMessage = message;
+		},
+		snapshot() {
+			return {
+				...budget,
+				usage: {
+					...usage,
+					elapsedMs: now() - startedAt
+				},
+				stopReason,
+				stopMessage,
+				handoffRequested,
+				handoffReason
+			};
+		}
+	};
+}
+//#endregion
+export { DELEGATION_BUDGETS, createDelegationBudgetPolicy, resolveDelegationBudget };

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

@@ -3,8 +3,8 @@ import { TaskRepository, init_task_repository } from "../../tasks/task-repositor
 import { getSessionConfig } from "../../storage/sqlite/config-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
 import { init_response_language, resolveResponseLanguage } from "../../i18n/response-language.js";
-import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { resolveTaskLocale } from "../../tasks/task-language.js";
+import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 //#region src/agent/prompt/response-language.ts
 init_response_language();
 init_sqlite();

package/dist/src/agent/prompt/sections/tooling.js

@@ -130,7 +130,7 @@ function buildToolingSection(params) {
 	const hasPublishArtifacts = availableTools.has("publish_artifacts");
 	const hasXopcUse = availableTools.has("xopc_use");
 	const orchestrationLines = [];
-	if (hasDelegate) orchestrationLines.push("- Sub-agent delegation → use `delegate_task(goal, context?, mode?, capabilities?, toolset?)`. Default research inherits available read capabilities; pass necessary context explicitly. Use implement for isolated worktree changes. Check rejectedTools and partial results before relying on the answer.");
+	if (hasDelegate) orchestrationLines.push("- Sub-agent delegation → use `delegate_task(goal, context?, mode?, capabilities?, toolset?, budgetTier?, maxIterations?)`. Choose light for narrow lookups, standard for bounded research, and deep for broader investigations. Supply relevant facts and a clear stopping condition; search before reading targeted chunks. Default research inherits available read capabilities. Use implement for isolated worktree changes. Inspect stopReason, budget usage, handoff and rejectedTools; resume incomplete work from the handoff rather than repeating the investigation.");
 	if (hasWorkflow) orchestrationLines.push("- Multi-phase workflows → use `workflow` to start persisted runs with subagents when a script defines phases.");
 	return [
 		"## Tooling",
@@ -152,7 +152,7 @@ function buildToolingSection(params) {
 		hasToolManual ? "Some complex tools have built-in manuals. Use `tool_manual(tool)` before non-trivial use." : "",
 		hasDelegate ? "If a task is complex or long-running, delegate it. Completion is push-based: the sub-agent result returns when done." : "",
 		...orchestrationLines,
-		"Do not poll delegate/workflow status in a tight loop; check on-demand or wait for completion."
+		hasDelegate || hasWorkflow ? "Do not poll delegate/workflow status in a tight loop; check on-demand or wait for completion." : ""
 	].filter(Boolean).join("\n");
 }
 function hasSkillsTools(toolNames) {

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

@@ -103,6 +103,12 @@ export declare class AgentService {
     applyRuntimeConfiguration(config: Config): void;
     getSkillCatalog(): SkillCatalogEntry[];
     getSkillCatalogSnapshot(): SkillCatalogSnapshot;
+    getAgentToolAvailability(agentId: string, name: string): {
+        condition: string;
+        state: "blocked" | "verified";
+        reasonCode: string;
+        detail: string;
+    };
     getAgentSkillAvailability(agentId: string): AgentSkillAvailabilityPayload;
     getSessionSkillAvailability(conversationId: string): Promise<AgentSkillAvailabilityPayload>;
     getSessionWorkspaceTrust(conversationId: string): Promise<WorkspaceTrustState>;

package/dist/src/agent/service.js

@@ -14,12 +14,12 @@ import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";
 import "../user-model/index.js";
+import { onSessionTranscriptUpdate } from "../session/transcript-events.js";
 import { runWithEmbeddedExecutionSession } from "./embedded/execution-context.js";
 import { removeSkillsLockEntry } from "./skills/hub-lock.js";
 import { installSkillFromZip } from "./skills/managed-store.js";
 import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "./skills/workspace-skills-dir.js";
 import { pullSkillFromSource } from "./skills/hub-pull.js";
-import { onSessionTranscriptUpdate } from "../session/transcript-events.js";
 import { persistInboundAttachments } from "../channels/attachments/inbound-persist.js";
 import { buildTranscriptUserMessage, hydrateUserTurnForLlm } from "./inbound/attachment-pipeline.js";
 import { drainEmbeddedSessionRunnerShutdowns } from "./embedded/session-runner.js";
@@ -496,6 +496,9 @@ var AgentService = class {
 	getSkillCatalogSnapshot() {
 		return this.agentManager.getSkillCatalogSnapshot();
 	}
+	getAgentToolAvailability(agentId, name) {
+		return this.agentManager.getAgentToolAvailability(agentId, name);
+	}
 	getAgentSkillAvailability(agentId) {
 		return this.agentManager.getAgentSkillAvailability(agentId);
 	}

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

@@ -2,10 +2,12 @@ import type { AgentEntry } from '../agent-config/index.js';
 export declare const STARTER_AGENTS_INITIALIZED_VERSION = 1;
 type StarterAgent = {
     id: string;
+    purpose?: AgentEntry['purpose'];
     tools?: AgentEntry['tools'];
     toolAllowlist?: AgentEntry['toolAllowlist'];
     skills?: AgentEntry['skills'];
     profile?: AgentEntry['profile'];
+    specialistProfile?: AgentEntry['specialistProfile'];
     profileFiles: Record<string, string>;
 };
 export declare const STARTER_AGENTS: readonly StarterAgent[];