@xopcai/xopc 0.0.381 → 0.0.383

package/dist/packages/gateway-contract/src/index.js

@@ -17,6 +17,7 @@ import { init_app_context } from "./app-context.js";
 import { init_browser_page_context } from "./browser-page-context.js";
 import { init_session_input_command } from "./session-input-command.js";
 import { init_welcome_suggestions } from "./welcome-suggestions.js";
+import { init_next_turn_suggestions } from "./next-turn-suggestions.js";
 import { init_home } from "./home.js";
 import { init_tool_activity } from "./tool-activity.js";
 import { init_automations } from "./automations.js";
@@ -42,6 +43,7 @@ import { init_usage } from "./usage.js";
 import { init_task_result_delivery } from "./task-result-delivery.js";
 import { init_session_command_rejection } from "./session-command-rejection.js";
 import { init_personal_proactivity } from "./personal-proactivity.js";
+import { init_specialists } from "./specialists.js";
 //#region packages/gateway-contract/src/index.ts
 var init_src = __esmMin((() => {
 	init_agent_stream();
@@ -58,6 +60,7 @@ var init_src = __esmMin((() => {
 	init_session_input_reliability();
 	init_session_input_command();
 	init_welcome_suggestions();
+	init_next_turn_suggestions();
 	init_home();
 	init_tool_activity();
 	init_automations();
@@ -87,6 +90,7 @@ var init_src = __esmMin((() => {
 	init_task_result_delivery();
 	init_session_command_rejection();
 	init_personal_proactivity();
+	init_specialists();
 }));
 //#endregion
 init_src();

package/dist/packages/gateway-contract/src/next-turn-suggestions.js

@@ -0,0 +1,40 @@
+import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
+import { z } from "zod";
+//#region packages/gateway-contract/src/next-turn-suggestions.ts
+var nextTurnSuggestionSchema, nextTurnSuggestionFeedbackSchema;
+var init_next_turn_suggestions = __esmMin((() => {
+	nextTurnSuggestionSchema = z.object({
+		id: z.string().uuid(),
+		conversationId: z.string(),
+		transcriptId: z.string(),
+		sourceRunId: z.string(),
+		inputRevision: z.number().int().nonnegative(),
+		transcriptCursor: z.number().int().nonnegative(),
+		agentId: z.string(),
+		locale: z.enum(["zh", "en"]),
+		prompt: z.string().min(1).max(160),
+		expiresAt: z.number()
+	});
+	z.object({
+		status: z.enum([
+			"ready",
+			"pending",
+			"none"
+		]),
+		suggestion: nextTurnSuggestionSchema.optional()
+	});
+	nextTurnSuggestionFeedbackSchema = z.object({
+		suggestionId: z.string().uuid(),
+		impressionId: z.string().uuid(),
+		event: z.enum([
+			"shown",
+			"accepted",
+			"dismissed",
+			"submitted"
+		]),
+		edited: z.boolean().optional()
+	}).strict();
+}));
+//#endregion
+init_next_turn_suggestions();
+export { init_next_turn_suggestions, nextTurnSuggestionFeedbackSchema, nextTurnSuggestionSchema };

package/dist/packages/gateway-contract/src/specialists.js

@@ -0,0 +1,48 @@
+import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
+import { z } from "zod";
+//#region packages/gateway-contract/src/specialists.ts
+function normalizeSpecialistRequirements(input) {
+	const parsed = SpecialistTaskRequirementsSchema.parse(input);
+	for (const field of [
+		"inputKinds",
+		"outputKinds",
+		"requiredTools",
+		"requiredSkills"
+	]) if (parsed[field]) parsed[field] = [...new Set(parsed[field])].sort();
+	return parsed;
+}
+var identifiers, SpecialistProfileSchema, SpecialistTaskRequirementsSchema;
+var init_specialists = __esmMin((() => {
+	identifiers = z.array(z.string().trim().min(1).max(80).toLowerCase()).max(16);
+	SpecialistProfileSchema = z.object({
+		version: z.literal(1),
+		domains: identifiers,
+		taskTypes: identifiers,
+		inputKinds: identifiers,
+		outputKinds: identifiers,
+		specialties: z.array(z.string().trim().min(1).max(120)).max(8),
+		examples: z.array(z.object({
+			request: z.string().trim().min(1).max(200),
+			deliverable: z.string().trim().min(1).max(200)
+		}).strict()).max(4),
+		limitations: z.array(z.string().trim().min(1).max(120)).max(8)
+	}).strict();
+	SpecialistTaskRequirementsSchema = z.object({
+		version: z.literal(1).default(1),
+		summary: z.string().trim().min(1).max(300),
+		domain: z.string().trim().min(1).max(80).toLowerCase().optional(),
+		taskType: z.string().trim().min(1).max(80).toLowerCase().optional(),
+		inputKinds: identifiers.optional(),
+		outputKinds: identifiers.optional(),
+		requiredTools: identifiers.optional(),
+		requiredSkills: identifiers.optional(),
+		requestedAgentId: z.string().trim().min(1).max(100).optional(),
+		connector: z.object({
+			connectorId: z.string().trim().min(1).max(200),
+			accountId: z.string().trim().min(1).max(200).optional()
+		}).strict().optional()
+	}).strict();
+}));
+//#endregion
+init_specialists();
+export { SpecialistProfileSchema, SpecialistTaskRequirementsSchema, init_specialists, normalizeSpecialistRequirements };

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

@@ -6,11 +6,9 @@ import { consumeClarificationApproval, init_clarification_wait_repository } from
 import { getInteractionState } from "../storage/sqlite/interaction-state-repository.js";
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
-import { resolveUserContextSessionAccess } from "../user-context/access-policy.js";
-import { enqueueConversationLearning } from "../memory-learning/repository.js";
 import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
 import { init_agent_scope, listAgentEntries, resolveAgentProfileDir } from "./agent-scope.js";
-import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
+import { extractTextContent } from "./context/workspace.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_paths, resolveBundledSkillsDir } from "../config/paths.js";
 import { CredentialResolver, init_credentials } from "../auth/credentials.js";
@@ -19,34 +17,36 @@ import { getApiKeySync, getDefaultModelSync, init_providers, resolveModel } from
 import { createExtensionAwareStreamFn } from "../providers/extension-stream-bridge.js";
 import { traceTools } from "../observability/runtime.js";
 import { continuesAfterTool, trackAiUsageStream } from "../usage/recorder.js";
-import { MemoryLearningService } from "../memory-learning/service.js";
-import { extractTextContent } from "./context/workspace.js";
-import { runPersistentLearningJob } from "./background-review/run-background-review.js";
-import { applyConfigOverrides } from "../config/runtime-overrides.js";
-import { isPersonalConversation } from "../personal-agent/repository.js";
-import { PersonalPromptContext } from "../personal-agent/prompt-context.js";
-import { buildExecutionScopeContextForPrompt } from "./context/execution-scope.js";
-import { clearBootstrapSnapshot } from "./bootstrap/bootstrap-cache.js";
-import { resolveBootstrapContextSync } from "./bootstrap/bootstrap-files.js";
-import { loadProjectAgentsContextFile } from "./bootstrap/project-agents-context.js";
-import { getEmbeddedExecutionRunId } from "./embedded/execution-context.js";
 import { loadSkillsLock } from "./skills/hub-lock.js";
 import { isUnderManagedSkillsDir } from "./skills/managed-store.js";
+import { maybeRequestChannelExecApproval } from "../channels/exec-approval-runtime.js";
+import { getEmbeddedExecutionRunId } from "./embedded/execution-context.js";
+import { isPersonalConversation } from "../personal-agent/repository.js";
+import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
+import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { createSkillConfigManager, isSkillEnabled, resolveSkillConfig } from "./skills/config.js";
 import { isValidSkillEnvVarName } from "./skills/required-env-vars.js";
 import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "./skills/workspace-skills-dir.js";
+import { resolveUserContextSessionAccess } from "../user-context/access-policy.js";
+import { evaluateToolGate } from "./context/execution-context.js";
 import { abortEmbeddedRun } from "./embedded/runs.js";
 import { evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner } from "./embedded/session-runner.js";
 import { createAgentTurnPolicy } from "./orchestration/agent-turn-policy.js";
+import { enqueueConversationLearning } from "../memory-learning/repository.js";
+import { MemoryLearningService } from "../memory-learning/service.js";
+import { runPersistentLearningJob } from "./background-review/run-background-review.js";
+import { PersonalPromptContext } from "../personal-agent/prompt-context.js";
+import { buildExecutionScopeContextForPrompt } from "./context/execution-scope.js";
+import { clearBootstrapSnapshot } from "./bootstrap/bootstrap-cache.js";
+import { resolveBootstrapContextSync } from "./bootstrap/bootstrap-files.js";
+import { loadProjectAgentsContextFile } from "./bootstrap/project-agents-context.js";
 import { createAgentCapabilitySessionState, resolveAgentCapabilityCatalog } from "./capabilities/registry.js";
 import "./capabilities/index.js";
 import { sortToolsForPromptCache } from "./tools/cache-stability.js";
 import { AgentToolsFactory } from "./tools/factory.js";
 import { isMemorySubsystemEnabled } from "./memory/memory-config.js";
-import { evaluateToolGate } from "./context/execution-context.js";
 import { ExecutionContextCoordinator } from "./context/coordinator.js";
 import { WorkspaceRuntimeRegistry } from "./workspace-runtime/registry.js";
-import { maybeRequestChannelExecApproval } from "../channels/exec-approval-runtime.js";
 import { SkillFilesystemWatcher } from "./skills/filesystem-watcher.js";
 import { ProjectTrustStore, hasTrustRequiringProjectResources } from "../project-trust/trust-store.js";
 import { replaceAgentSystemPrompt } from "./prompt/agent-system-prompt.js";
@@ -552,7 +552,7 @@ var AgentManager = class {
 			status: rt.skillManager.getStatus()
 		};
 	}
-	buildAgentSkillAvailability(unresolvedProfile, workspaceDir, registeredToolNames) {
+	buildAgentSkillAvailability(unresolvedProfile, workspaceDir, registeredToolNames, conversationId) {
 		const rt = this.workspaceRuntimes.getOrCreate(workspaceDir, unresolvedProfile.agentId);
 		const profile = this.materializeSkillAllowlist(unresolvedProfile, rt);
 		const entry = listAgentEntries().find((agent) => agent.enabled !== false && agent.id.toLowerCase() === profile.agentId.toLowerCase());
@@ -561,6 +561,7 @@ var AgentManager = class {
 		const workspaceLock = loadSkillsLock(resolveWorkspaceSkillsLockPath(workspaceDir));
 		const allow = profile.skillsAllowlist === void 0 ? void 0 : new Set(profile.skillsAllowlist.map((s) => s.toLowerCase()));
 		const tools = registeredToolNames ?? this.toolsFactory.createAllTools({
+			conversationId,
 			workspace: workspaceDir,
 			profileMarkdownRoot: resolveAgentProfileDir(profile.agentId),
 			agentId: profile.agentId,
@@ -608,7 +609,7 @@ var AgentManager = class {
 	}
 	getAgentSkillAvailability(agentId) {
 		const profile = resolveEffectiveAgentProfile(agentId);
-		return this.buildAgentSkillAvailability(profile, profile.resolvedWorkspacePath);
+		return this.buildAgentSkillAvailability(profile, profile.resolvedWorkspacePath, void 0, "");
 	}
 	getWorkflowSkillInstructions(agentId, names) {
 		const requested = [...new Set(names.map((name) => name.trim()).filter(Boolean))];
@@ -627,7 +628,7 @@ var AgentManager = class {
 	}
 	getSessionSkillAvailability(conversationId) {
 		const profile = resolveEffectiveAgentProfileForSession(conversationId);
-		return this.buildAgentSkillAvailability(profile, this.getResolvedWorkspaceForSession(conversationId), this.agents.get(conversationId)?.registeredToolNames);
+		return this.buildAgentSkillAvailability(profile, this.getResolvedWorkspaceForSession(conversationId), this.agents.get(conversationId)?.registeredToolNames, conversationId);
 	}
 	getSessionWorkspaceTrust(conversationId) {
 		return this.getWorkspaceTrust(this.getResolvedWorkspaceForSession(conversationId));

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

@@ -5,7 +5,7 @@ import { AgentCatalogRepository, init_repository } from "../agent-catalog/reposi
 import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
 import { init_workspace_defaults, resolveDefaultAgentWorkspaceDir } from "../config/workspace-defaults.js";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
-import fs from "node:fs";
+import fsSync from "node:fs";
 //#region src/agent/agent-scope.ts
 /** Agent path and list resolution backed by the SQLite Agent catalog. */
 /** Expand `~` and resolve to an absolute path. */
@@ -51,7 +51,7 @@ function normalizePathForComparison(input) {
 	const resolved = resolve(resolveUserPath(input));
 	let normalized = resolved;
 	try {
-		normalized = fs.realpathSync.native(resolved);
+		normalized = fsSync.realpathSync.native(resolved);
 	} catch {}
 	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }

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

@@ -1,5 +1,5 @@
-import { USER_UNDERSTANDING_MAINTENANCE_POLICY } from "../../user-model/maintenance-policy.js";
 import { USER_FACING_UNDERSTANDING_WRITING_GUIDANCE } from "../../user-context/understanding-writing.js";
+import { USER_UNDERSTANDING_MAINTENANCE_POLICY } from "../../user-model/maintenance-policy.js";
 //#region src/agent/background-review/prompts.ts
 const USER_MODEL_MAINTAINER_SYSTEM_PROMPT = `You are xopc's user-understanding maintainer. You do not chat with the user and cannot write storage. Distinguish explicit memory commands, corrections, forgetting, durable user assertions, durable goals, collaboration rules, and ordinary task requests. Return strict JSON only. Assistant text is never evidence about the user.\n\n${USER_UNDERSTANDING_MAINTENANCE_POLICY}\n\n${USER_FACING_UNDERSTANDING_WRITING_GUIDANCE}`;
 function buildUserModelInterpreterPrompt(options) {

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

@@ -5,26 +5,26 @@ import { finishContextExtractionRun } from "../../storage/sqlite/context-extract
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { loadCompactionSourceSnapshot } from "../../storage/sqlite/transcript-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
-import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
-import { failLearningJob, finishLearningJob, learningPolicyHash } from "../../memory-learning/repository.js";
-import { extractProfileAgentId } from "../../config/agent-profile.js";
-import { resolveModelIntentRef, resolveModelSelector } from "../../config/agent-model-intents.js";
+import { extractTextContent } from "../context/workspace.js";
+import { getAssertionSlot, listUserAssertions } from "../../user-model/repository.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../../auth/sync-provider-auth.js";
 import { getApiKeySync, init_providers, resolveModel } from "../../providers/index.js";
 import { createExtensionAwareStreamFn } from "../../providers/extension-stream-bridge.js";
 import { trackAiUsageStream } from "../../usage/recorder.js";
-import { isLoopbackModel } from "../../providers/local-model.js";
+import { extractProfileAgentId } from "../../config/agent-profile.js";
+import { resolveModelIntentRef, resolveModelSelector } from "../../config/agent-model-intents.js";
 import { claimRegisteredExtraction } from "../../user-context/extraction/registry.js";
-import { applyWorkCandidates } from "../../memory-learning/work-capture.js";
+import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
 import { stripRuntimeContextFromUserMessage } from "../../session/user-message-display.js";
-import { getAssertionSlot, listUserAssertions } from "../../user-model/repository.js";
+import { readAgentMessageContent } from "../memory/agent-message-access.js";
+import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
+import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
+import { failLearningJob, finishLearningJob, learningPolicyHash } from "../../memory-learning/repository.js";
+import { isLoopbackModel } from "../../providers/local-model.js";
+import { applyWorkCandidates } from "../../memory-learning/work-capture.js";
 import { emptyUserModelCaptureResult, executeUserModelInterpretation } from "../../user-model/capture/executor.js";
 import { parseUserModelInterpretation } from "../../user-model/capture/semantic.js";
 import "../../user-model/capture/index.js";
-import { extractTextContent } from "../context/workspace.js";
-import { readAgentMessageContent } from "../memory/agent-message-access.js";
-import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
-import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
 import { USER_MODEL_MAINTAINER_SYSTEM_PROMPT, buildUserModelInterpreterPrompt } from "./prompts.js";
 import { Agent } from "@earendil-works/pi-agent-core";
 //#region src/agent/background-review/run-background-review.ts

package/dist/src/agent/child-agent-factory.d.ts

@@ -4,6 +4,7 @@ import type { Config } from '../config/schema.js';
 import type { EndpointToolRuntime } from '../endpoint-tools/index.js';
 import type { MessageBus } from '../infra/bus/index.js';
 import { type EmbeddedTranscriptRuntime } from './embedded/transcript-runtime.js';
+import { createDelegationBudgetPolicy, type DelegationBudgetTier, type DelegationStopReason } from './orchestration/delegation-budget.js';
 import type { RunVerification } from './coding/run-verification.js';
 import type { ToolExecutorConfig } from './tools/executor.js';
 export interface BuildChildToolsOptions {
@@ -39,6 +40,7 @@ export interface DelegateChildHandleOptions {
     requesterConversationId?: string;
     allowedToolNames: string[];
     maxIterations: number;
+    budgetTier?: DelegationBudgetTier;
     model: Model<Api>;
     bus: MessageBus;
     agentId?: string;
@@ -62,6 +64,13 @@ export interface DelegateChildRunResult {
     toolIterations: number;
     messages: AgentMessage[];
     status: 'success' | 'failed' | 'cancelled' | 'partial';
+    stopReason: DelegationStopReason;
+    budget: ReturnType<ReturnType<typeof createDelegationBudgetPolicy>['snapshot']>;
+    handoff: {
+        requested: boolean;
+        completed: boolean;
+        summary: string;
+    };
     verification?: Awaited<ReturnType<RunVerification['summary']>>;
 }
 export interface DelegateChildHandle {

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/coding/repository-instructions.js

@@ -1,5 +1,5 @@
-import { validateDataBatch } from "../data-acquisition/schema.js";
 import { isDataBatchResult } from "../data-acquisition/render.js";
+import { validateDataBatch } from "../data-acquisition/schema.js";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";

package/dist/src/agent/context/coordinator.js

@@ -1,8 +1,8 @@
 import { extractProfileAgentId } from "../../config/agent-profile.js";
-import { assembleTaskContext } from "../../tasks/task-context-assembler.js";
 import { recordExecutionContext } from "./audit.js";
-import { extractAgentUserPlainText } from "../memory/user-message-text.js";
 import { buildExecutionContext, fitExecutionContextToChars } from "./execution-context.js";
+import { assembleTaskContext } from "../../tasks/task-context-assembler.js";
+import { extractAgentUserPlainText } from "../memory/user-message-text.js";
 //#region src/agent/context/coordinator.ts
 var ExecutionContextCoordinator = class {
 	queriesBySession = /* @__PURE__ */ new Map();

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

@@ -1,14 +1,14 @@
 import { getSqliteDatabase, init_transaction } from "../../storage/sqlite/transaction.js";
 import { init_collaboration_rule_repository, listCollaborationRules } from "../../storage/sqlite/collaboration-rule-repository.js";
-import { canUseKnowledge } from "../../knowledge-memory/usage-policy.js";
-import { listKnowledgeItems, searchKnowledgeItems } from "../../knowledge-memory/repository.js";
-import "../../knowledge-memory/index.js";
 import { listUserAssertions } from "../../user-model/repository.js";
 import { calculateExecutionValue } from "../../user-model/importance.js";
 import { canUseAssertion } from "../../user-model/usage-policy.js";
+import { canUseKnowledge } from "../../knowledge-memory/usage-policy.js";
+import { listKnowledgeItems, searchKnowledgeItems } from "../../knowledge-memory/repository.js";
+import "../../knowledge-memory/index.js";
 import { retrievalLexicalSimilarity } from "../../retrieval/textFeatures.js";
-import { getExecutionContextFeedbackScores } from "./audit.js";
 import { buildUserContextBlock } from "../memory/context-fence.js";
+import { getExecutionContextFeedbackScores } from "./audit.js";
 import { randomUUID } from "node:crypto";
 //#region src/agent/context/execution-context.ts
 init_transaction();

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 { 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 { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
+import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { buildActiveProjectContextForPrompt } from "./project-context.js";
 //#region src/agent/context/execution-scope.ts
 init_sqlite();

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

@@ -1,13 +1,13 @@
 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 { ProjectStore } from "../../projects/project-store.js";
+import { getProjectForSession, getProjectWorkspacePathForSession } from "../../projects/workspace.js";
 import { canUseKnowledge } from "../../knowledge-memory/usage-policy.js";
 import { listKnowledgeItems, searchKnowledgeItems } from "../../knowledge-memory/repository.js";
 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 { LocalAppStore } from "../../local-apps/store.js";
 //#region src/agent/context/project-context.ts
 init_sqlite();

package/dist/src/agent/data-acquisition/service.js

@@ -1,7 +1,7 @@
 import { executeWithTimeout } from "../lifecycle/timeout-wrapper.js";
 import { checkedFilePath, readWorkspaceFileAsync } from "../sandbox/fileAccess.js";
-import { dataScheduler } from "./scheduler.js";
 import { checkFileSafety } from "../prompt/safety.js";
+import { dataScheduler } from "./scheduler.js";
 import { parseRepositoryMatch, repositorySearch } from "../tools/repository-search.js";
 import { DATA_OPERATION_TOOLS, nativeDataArgs, validateDataBatch } from "./schema.js";
 import { readGitData } from "./git.js";

package/dist/src/agent/embedded/codemode-extension.js

@@ -1,6 +1,6 @@
-import { isCodemodeCoreRead } from "../tools/codemode-permissions.js";
 import { getXopcToolMetadata } from "./tool-metadata.js";
 import { withDataToolPermissions } from "../tools/dataBatch.js";
+import { isCodemodeCoreRead } from "../tools/codemode-permissions.js";
 import { retainCodemodeOutput } from "./codemode-output.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createCodemodeExtension } from "@earendil-works/pi-coding-agent";

package/dist/src/agent/embedded/index.js

@@ -1,7 +1,7 @@
 import { getEmbeddedExecutionRunId, getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
-import { abortEmbeddedRun, getEmbeddedRunByConversationId, queueEmbeddedSteer } from "./runs.js";
 import { DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, resolveLiveToolResultMaxChars, truncateToolResultMessage } from "./tool-result-truncation.js";
 import { getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard } from "./session-tool-result-guard.js";
+import { abortEmbeddedRun, getEmbeddedRunByConversationId, queueEmbeddedSteer } from "./runs.js";
 import { acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest } from "./session-runner.js";
 import { repairAssistantUsageInSessionManager } from "./session-manager-init.js";
 import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";

package/dist/src/agent/embedded/run-for-session.js

@@ -2,21 +2,21 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { parseTurnOutcome } from "../../../packages/gateway-contract/src/turn-outcome.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
-import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
 import { appendDynamicPromptSection } from "../prompt/cache-boundary.js";
 import { setTraceIdentity, startObservation, traceOperation, traceRun } from "../../observability/runtime.js";
-import { resolveAgentTurnTimeoutMs } from "../orchestration/run-agent-turn-with-timeout.js";
-import { isPersonalConversation } from "../../personal-agent/repository.js";
-import { filterExecutionTools, resolveExecutionToolPolicy } from "./execution-tool-policy.js";
 import { runWithEmbeddedExecutionSession } from "./execution-context.js";
+import { isPersonalConversation } from "../../personal-agent/repository.js";
+import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { resolvePromptCachePolicy } from "../../providers/prompt-cache-plan.js";
 import { prepareNativeMcpConfig } from "../mcp/native-mcp.js";
+import { filterExecutionTools, resolveExecutionToolPolicy } from "./execution-tool-policy.js";
 import { evaluateContextBudget } from "../memory/context-budget.js";
-import { assessContext, recoverContext as recoverContext$1 } from "../memory/context-recovery.js";
 import { resolveCompactionPolicy } from "../memory/compaction-policy.js";
-import { runXopcEmbeddedTurn } from "./run-turn.js";
 import { projectTurnOutcome } from "../../session/turn-outcome-projector.js";
+import { resolveAgentTurnTimeoutMs } from "../orchestration/run-agent-turn-with-timeout.js";
+import { assessContext, recoverContext as recoverContext$1 } from "../memory/context-recovery.js";
+import { runXopcEmbeddedTurn } from "./run-turn.js";
 import { voicePresentationPrompt } from "../prompt/voice-presentation.js";
 import { applyStartupContextToUserMessage } from "../reply/apply-turn-user-enrichment.js";
 import { AgentRunSupervisor } from "../orchestration/agent-run-supervisor.js";