@sema-agent/core 2.1.0 → 2.3.0

package/dist/core/runner/prepare-task.js

@@ -28,7 +28,7 @@ import { cloneObserverInput, formatHookFeedback, runToolGate } from "../hooks.js
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
-import { defineTool } from "../tools.js";
+import { defineTool, isDefineToolProduct } from "../tools.js";
 import { canonicalToolName } from "../tool-name-aliases.js";
 import { pathToUri } from "../lsp-protocol.js";
 import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, buildToolResultRef, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, isVolatileOffloadStore, OFFLOAD_TOOL_NAME, createReadToolResultTool, withToolResultOffload, } from "../tool-result-store.js";
@@ -93,6 +93,9 @@ export function resolveModelPromptTraits(model, spec, internals) {
         fableMitigations: isFableFamilyModelId(model.id),
     };
 }
+function isDelegatedNonForkChild(internals) {
+    return internals?.isDelegatedChild === true && internals?.insideFork !== true;
+}
 export function batchContextAt(messages, currentId) {
     let batch = [];
     for (const m of messages) {
@@ -742,6 +745,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             model: harnessRef.current?.getModel(),
             thinkingLevel: harnessRef.current?.getThinkingLevel(),
             principal: spec.principal,
+            oneShot: spec.oneShot,
             clientContext: spec.clientContext,
             excludeTools: toolFaceSnapshot.exclude,
             deferTools: toolFaceSnapshot.defer,
@@ -792,10 +796,15 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             requestStopAfterTurn,
             ...(spec.enablePlanMode === true ? { enterPlanMode } : {}),
         });
-        const tools = (spec.tools ?? []).map((t) => maybeOffload(defineTool({
-            ...t,
-            execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
-        }), t));
+        const tools = (spec.tools ?? []).map((t) => {
+            if (isDefineToolProduct(t)) {
+                return maybeOffload(t, t);
+            }
+            return maybeOffload(defineTool({
+                ...t,
+                execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
+            }), t);
+        });
         const blockedRef = {};
         if (spec.enableBlockedReport !== false) {
             tools.push(createReportBlockedTool(blockedRef));
@@ -1164,6 +1173,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 taskRegistry: defaultTaskRegistry,
                 taskOwner: hostTaskId,
                 taskScope,
+                oneShot: spec.oneShot,
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
                 ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
@@ -1212,7 +1222,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         if (backgroundTaskToolsActive || workflowToolsActive) {
             toolEffects.set("TaskOutput", "read");
             toolEffects.set("TaskStop", "write");
-            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
             if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
                 const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
                 const reviveSpawn = delegationForRevive !== undefined && deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined
@@ -1272,6 +1282,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { onTaskNotification: internals.onTaskNotification } : {}),
                 ...(handsCwdRef !== undefined ? { cwdRef: handsCwdRef } : {}),
+                ...(offloadStore !== undefined ? { toolResultStore: offloadStore } : {}),
             })));
         }
         if (handsCwdRef !== undefined) {
@@ -1405,7 +1416,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 loaded = await Promise.resolve(deps.loadProjectMemory({
                     cwd: taskRootPath,
                     handsEnabled,
-                    isSubagent: internals?.parentTaskId !== undefined,
+                    isSubagent: isDelegatedNonForkChild(internals),
                     ...(internals?.agentName ? { agentName: internals.agentName } : {}),
                     sessionId,
                     phase: projectMemoryPhase,
@@ -1432,6 +1443,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 memoryBlock = memoryBlock ? `${memoryBlock}\n\n${projectBlock}` : projectBlock;
             }
         }
+        const declaredSkillRank = new Map();
+        for (const s of spec.skills ?? [])
+            if (!declaredSkillRank.has(s.name))
+                declaredSkillRank.set(s.name, declaredSkillRank.size);
         const skillSpecs = normalizeSkills(spec.skills ?? []).filter((s) => {
             if (s.content.length <= SKILL_CONTENT_MAX_CHARS)
                 return true;
@@ -1457,6 +1472,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     name: s.name,
                     description: s.description,
                     ...(s.files !== undefined ? { files: s.files.map((f) => ({ path: f.path })) } : {}),
+                    ...(declaredSkillRank.get(s.name) !== undefined ? { declaredRank: declaredSkillRank.get(s.name) } : {}),
                 })),
                 seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
             }
@@ -1485,7 +1501,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             awarenessEnabled: thinking !== undefined && ULTRA_REASONING_TIERS.has(thinking),
             worktreeIsolated: internals?.isolation === "worktree" && ownedEnv !== undefined,
             withinTaskCompactionEnabled: (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true),
-            isSubagent: internals?.isDelegatedChild === true && internals?.insideFork !== true,
+            isSubagent: isDelegatedNonForkChild(internals),
         };
         const userSystemPrompt = spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals?.defaultSystemPrompt;
         const userAppendSystemPrompt = spec.appendSystemPrompt;
@@ -2382,7 +2398,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : foldedPolicy;
         const hooks = spec.hooks ?? deps.hooks;
         const onAsk = spec.onAsk ?? deps.onAsk;
-        const handWriteTools = handsEnabled
+        const handWriteTools = handsEnabled && spec.handsReadOnly !== true
             ? Object.keys(HAND_TOOL_EFFECTS).filter((name) => {
                 const eff = HAND_TOOL_EFFECTS[name];
                 return eff === "write" || eff === "idempotent";
@@ -3167,15 +3183,29 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const onCompactionApplied = handsEnabled && readFileStateForCheckpoint
             ? (attachedComplete, preserveReadState) => applyCompactionToReadFileState(readFileStateForCheckpoint, attachedComplete, preserveReadState)
             : undefined;
+        const changedFilesReadDenied = denyNarrowingPolicy === undefined
+            ? undefined
+            : async (path) => {
+                try {
+                    const d = await denyNarrowingPolicy.check({ toolName: "Read", args: { file_path: path }, toolCallId: "changed-files-visibility-probe" }, abortController.signal);
+                    return d.action === "deny";
+                }
+                catch {
+                    return false;
+                }
+            };
         const detectExternalChanges = handsEnabled && readFileStateForCheckpoint
             ? async (maxFiles) => {
                 const candidates = [...readFileStateForCheckpoint.entries()]
                     .filter(([, e]) => e.lastReadAt !== undefined)
+                    .filter(([, e]) => e.truncated !== true)
                     .sort((a, b) => (b[1].lastReadAt ?? 0) - (a[1].lastReadAt ?? 0))
                     .slice(0, Math.max(0, maxFiles));
                 const changed = [];
                 const evicted = [];
                 for (const [path, entry] of candidates) {
+                    if (changedFilesReadDenied !== undefined && (await changedFilesReadDenied(path)))
+                        continue;
                     try {
                         const info = await executionEnv.fileInfo(path, abortController.signal);
                         if (!info.ok) {
@@ -3249,7 +3279,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -26,6 +26,7 @@ import { cacheFamilyOf, usageCostMicroUsd } from "./usage-accounting.js";
 import { assembleResult, errorCodeOf } from "./assemble-result.js";
 import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
 import { prepareTask } from "./prepare-task.js";
+import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { hasVerifiableStructureSignal } from "./grounding-signal.js";
 import { hasDestroy, isIsolated } from "../remote-env.js";
 import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
@@ -44,7 +45,7 @@ import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
 export { DEFAULT_MAX_TURNS };
 function createRunState() {
     return {
-        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, tracer: undefined, taskId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
+        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, pricingConfigured: true, unpricedSpend: false, tracer: undefined, taskId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
         degrade: { degradeToModel: undefined, degraded: undefined, outputErrorStreak: 0, outputInvalid: false, recordDegraded: () => { } },
         limits: { turnsExceeded: false, budgetHit: undefined, outputRetryCap: 0, effectiveMaxTurns: undefined },
         budget: { remainingMicroUsd: undefined, maxCostMicroUsd: undefined, overBudget: () => false, streamCancel: false, callOutputChars: 0, lastStreamBudgetCheck: 0, projectedOverBudget: () => false },
@@ -150,6 +151,8 @@ function writeFamilyOfCanonical(name) {
         return "task";
     if (name === "TodoWrite")
         return "todo";
+    if (name === TOOL_SEARCH_NAME)
+        return "tool_search";
     return undefined;
 }
 function toolResultMsg(toolCallId, toolName, text, isError) {
@@ -366,6 +369,10 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 const mcpRemovals = mcpInstructionsOn && mcpDelta.pendingRemovals.length > 0 ? [...mcpDelta.pendingRemovals] : undefined;
                 const mcpDropped = mcpInstructionsOn && prepared.mcp.droppedTools.length > 0 ? selectMcpDroppedBatch(prepared.mcp.droppedTools) : undefined;
                 const budgetUsdOn = rs.attach.attachmentsCfg?.budgetUsd === true && rs.budget.maxCostMicroUsd !== undefined && rs.turn.lastTurnHadToolCalls;
+                const toolSearchReminderOn = rs.attach.attachmentsCfg?.toolSearchReminder === true && prepared.deferredToolNames !== undefined;
+                const undiscoveredTools = toolSearchReminderOn
+                    ? [...prepared.deferredToolNames].filter((n) => !prepared.activeTools.has(n)).sort()
+                    : undefined;
                 due.push(...collectDueAttachments(rs.attach.attachState, {
                     turn: stats.turns,
                     cadenceTurn: rs.counters.cadenceTurns,
@@ -375,6 +382,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     config: {
                         todoReminder: rs.attach.attachmentsCfg?.todoReminder === true,
                         ...(rs.attach.attachmentsCfg?.todoReminderMode !== undefined ? { todoReminderMode: rs.attach.attachmentsCfg.todoReminderMode } : {}),
+                        toolSearchReminder: toolSearchReminderOn,
                         changedFiles: changedFilesOn,
                         planModeReminder: rs.attach.attachmentsCfg?.planModeReminder === true,
                         budgetUsd: budgetUsdOn,
@@ -384,6 +392,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                         skillsListing: rs.attach.skillsListingOn,
                         mcpInstructions: mcpInstructionsOn,
                     },
+                    ...(undiscoveredTools !== undefined && undiscoveredTools.length > 0 ? { undiscoveredTools } : {}),
                     ...(changed !== undefined ? { changedFiles: changed } : {}),
                     ...(budgetUsdOn && rs.budget.maxCostMicroUsd !== undefined
                         ? { budgetUsd: { used: stats.costMicroUsd / 1e6, total: rs.budget.maxCostMicroUsd / 1e6 } }
@@ -779,6 +788,8 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             const u = m.usage;
             stats.tokens += u.totalTokens || 0;
             const { totalInputTokens: turnInput, costMicroUsd: turnCostMicroUsd } = usageCostMicroUsd(rs.telemetry.cacheFamily, u, rs.telemetry.pricing);
+            if (!rs.telemetry.pricingConfigured)
+                rs.telemetry.unpricedSpend = true;
             stats.promptTokens += turnInput;
             stats.cachedTokens += u.cacheRead || 0;
             stats.cacheWriteTokens += u.cacheWrite || 0;
@@ -817,7 +828,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 latencyMs: rs.turn.callStartAt !== undefined ? callEndAt - rs.turn.callStartAt : 0,
                 firstTokenMs: rs.turn.callStartAt !== undefined && rs.turn.firstTokenAt !== undefined ? rs.turn.firstTokenAt - rs.turn.callStartAt : undefined,
                 ...(callIssuedAt !== undefined ? { callStartedAt: callIssuedAt } : {}),
-                costMicroUsd: turnCostMicroUsd,
+                ...(rs.telemetry.pricingConfigured ? { costMicroUsd: turnCostMicroUsd } : {}),
                 ...(capLast !== undefined ? { callCap: capLast.cap, capThinkingSkipped: capLast.thinkingSkipped } : {}),
                 ...(m.role === "assistant" && typeof m.stopReason === "string"
                     ? { stopReason: m.stopReason }
@@ -1619,6 +1630,7 @@ export class Runner {
         const rs = createRunState();
         rs.telemetry.cacheFamily = cacheFamilyOf(prepared.model);
         rs.telemetry.pricing = this.deps.pricing?.[prepared.model.id] ?? modelCostToPricing(prepared.model.cost);
+        rs.telemetry.pricingConfigured = this.deps.pricing?.[prepared.model.id] !== undefined || prepared.model.cost !== undefined;
         if (spec.degrade) {
             try {
                 rs.degrade.degradeToModel = resolveModel(spec.degrade.to, this.deps.models);
@@ -1660,11 +1672,17 @@ export class Runner {
             }
             if (m) {
                 rs.telemetry.pricing = this.deps.pricing?.[m.id] ?? modelCostToPricing(m.cost);
+                rs.telemetry.pricingConfigured = this.deps.pricing?.[m.id] !== undefined || m.cost !== undefined;
                 rs.telemetry.cacheFamily = cacheFamilyOf(m);
             }
             else {
-                if (this.deps.pricing?.[info.to])
+                if (this.deps.pricing?.[info.to]) {
                     rs.telemetry.pricing = this.deps.pricing[info.to];
+                    rs.telemetry.pricingConfigured = true;
+                }
+                else {
+                    rs.telemetry.pricingConfigured = false;
+                }
                 rs.telemetry.cacheFamily = "input-excludes-cached";
             }
             rs.degrade.degraded = info;
@@ -2067,6 +2085,9 @@ export class Runner {
                 return;
             const fam = cacheFamilyOf(m);
             const price = this.deps.pricing?.[m.id] ?? modelCostToPricing(m.cost);
+            const priced = this.deps.pricing?.[m.id] !== undefined || m.cost !== undefined;
+            if (!priced)
+                rs.telemetry.unpricedSpend = true;
             const { totalInputTokens, costMicroUsd } = usageCostMicroUsd(fam, u, price);
             stats.tokens += u.totalTokens || 0;
             stats.promptTokens += totalInputTokens;
@@ -2079,7 +2100,7 @@ export class Runner {
                 kind: "brain.call", version: 1, taskId: rs.telemetry.taskId, model: m.id, provider: m.provider,
                 promptTokens: totalInputTokens, completionTokens: u.output || 0,
                 cacheRead: u.cacheRead || 0, cacheWrite: u.cacheWrite || 0,
-                latencyMs: 0, costMicroUsd, ...(typeof msg?.stopReason === "string" ? { stopReason: msg.stopReason } : {}), ts: Date.now(),
+                latencyMs: 0, ...(priced ? { costMicroUsd } : {}), ...(typeof msg?.stopReason === "string" ? { stopReason: msg.stopReason } : {}), ts: Date.now(),
             }));
         };
         const compactionBrain = {
@@ -2708,6 +2729,7 @@ export class Runner {
             const result = assembleResult(spec, prepared.sessionId, final, stats, {
                 threw,
                 model: prepared.model.id,
+                unpricedSpend: rs.telemetry.unpricedSpend,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,
                 abortedLive,
@@ -2826,7 +2848,7 @@ export class Runner {
                 errorCode: result.errorCode,
                 turns: stats.turns,
                 tokens: stats.tokens,
-                costMicroUsd: stats.costMicroUsd,
+                ...(rs.telemetry.unpricedSpend ? {} : { costMicroUsd: stats.costMicroUsd }),
                 durationMs: Date.now() - rs.telemetry.taskStart,
                 ...(prepared.outputRef.set ? { hasStructuredOutput: true } : {}),
                 ...(stats.mechanisms !== undefined

package/dist/core/runner/synthetic-tools.d.ts

@@ -47,6 +47,7 @@ export interface SkillListingEntry {
     files?: Array<{
         path: string;
     }>;
+    declaredRank?: number;
 }
 export declare function normalizeSkills(skills: SkillLike[] | undefined): SkillLike[];
 export declare const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";

package/dist/core/runner/synthetic-tools.js

@@ -85,7 +85,7 @@ export function createReportFindingsTool() {
 }
 export const SKILL_TOOL_NAME = "Skill";
 export const SKILL_CONTENT_MAX_CHARS = 1024 * 1024;
-const SKILL_DESC_MAX_CHARS = 1_000;
+const SKILL_DESC_MAX_CHARS = 1_536;
 export const SKILLS_BLOCK_MAX_BYTES = 8_000;
 export const SKILL_ATTACHMENTS_MAX_CHARS = 50_000;
 export const SKILL_ATTACHMENT_PATH_MAX_CHARS = 512;
@@ -121,11 +121,11 @@ export function normalizeSkills(skills) {
 export const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";
 export function skillListingLine(s) {
     const desc = s.description.length > SKILL_DESC_MAX_CHARS
-        ? `${s.description.slice(0, SKILL_DESC_MAX_CHARS)}…[description truncated]`
+        ? `${s.description.slice(0, SKILL_DESC_MAX_CHARS - 1)}…`
         : s.description;
     return `- ${s.name}: ${desc}${skillFilesSuffix(s.files)}`;
 }
-const SKILLS_BLOCK_CAP_MARKER = "(block size cap reached — remaining skills listed name-only; descriptions via the tool)";
+const SKILLS_BLOCK_CAP_MARKER = "(block size cap reached — lower-priority skills are listed name-only; descriptions via the tool)";
 export function buildSkillsBlock(skills) {
     if (skills.length === 0)
         return undefined;
@@ -145,20 +145,23 @@ export function buildSkillsBlock(skills) {
     const fullTotal = fullLines.reduce((acc, l) => acc + lineCost(l), 0);
     if (fullTotal <= budget)
         return render(fullLines);
-    const suffixNameCost = new Array(skills.length + 1);
-    suffixNameCost[skills.length] = 0;
-    for (let i = skills.length - 1; i >= 0; i--)
-        suffixNameCost[i] = suffixNameCost[i + 1] + lineCost(nameLines[i]);
     const markerCost = lineCost(SKILLS_BLOCK_CAP_MARKER);
-    let bestK = -1;
-    let prefixCost = 0;
-    for (let k = 0; k < skills.length; k++) {
-        if (prefixCost + markerCost + suffixNameCost[k] <= budget)
-            bestK = k;
-        prefixCost += lineCost(fullLines[k]);
+    const floorCost = markerCost + nameLines.reduce((acc, l) => acc + lineCost(l), 0);
+    if (floorCost <= budget) {
+        let slack = budget - floorCost;
+        const byPriority = skills
+            .map((s, i) => ({ i, rank: s.declaredRank ?? i }))
+            .toSorted((a, b) => a.rank - b.rank || a.i - b.i);
+        const withDescription = new Set();
+        for (const { i } of byPriority) {
+            const delta = lineCost(fullLines[i]) - lineCost(nameLines[i]);
+            if (delta <= slack) {
+                withDescription.add(i);
+                slack -= delta;
+            }
+        }
+        return render([SKILLS_BLOCK_CAP_MARKER, ...skills.map((_s, i) => (withDescription.has(i) ? fullLines[i] : nameLines[i]))]);
     }
-    if (bestK >= 0)
-        return render([...fullLines.slice(0, bestK), SKILLS_BLOCK_CAP_MARKER, ...nameLines.slice(bestK)]);
     for (let m = skills.length - 1; m >= 0; m--) {
         const overflowLine = `(… +${skills.length - m} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`;
         const cost = markerCost + nameLines.slice(0, m).reduce((acc, l) => acc + lineCost(l), 0) + lineCost(overflowLine);

package/dist/core/runner/turn-attachments.d.ts

@@ -7,10 +7,14 @@ export declare const PLAN_MODE_ATTACHMENT_CONFIG: {
     readonly TURNS_BETWEEN_ATTACHMENTS: 5;
     readonly FULL_REMINDER_EVERY_N_ATTACHMENTS: 5;
 };
+export declare const TOOL_SEARCH_REMINDER_CONFIG: {
+    readonly EVERY_N_TURNS: 15;
+    readonly MAX_NAMES: 10;
+};
 export declare const CHANGED_FILES_MAX = 20;
 export declare const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export declare const ATTACHMENT_BYTE_CAP: number;
-export type AttachmentSource = "todo_reminder" | "task_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
+export type AttachmentSource = "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
 export interface AgentListingEntry {
     name: string;
     description: string;
@@ -42,6 +46,8 @@ export interface AttachmentState {
     todoLastWriteTurn?: number;
     lastTodoReminderTurn: number;
     lastTaskReminderTurn: number;
+    toolSearchLastUseTurn?: number;
+    lastToolSearchReminderTurn: number;
     planAttachmentCount: number;
     lastPlanReminderTurn: number;
     surfacedMtime: Map<string, number>;
@@ -60,7 +66,7 @@ export interface InstructionsChangeState {
 export declare const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
 export declare function createAttachmentState(): AttachmentState;
 export declare function reduceToolEnd(state: AttachmentState, details: unknown): void;
-export type WriteFamily = "todo" | "task";
+export type WriteFamily = "todo" | "task" | "tool_search";
 export declare function stampWriteAnchor(state: AttachmentState, family: WriteFamily, clock: number): void;
 export declare function advanceCadenceClock(state: AttachmentState, clock: number, content: unknown, writeFamilyOf: (toolName: string) => WriteFamily | undefined): number;
 export declare function rebaseCadenceWindows(state: AttachmentState, clock: number): void;
@@ -77,6 +83,7 @@ export interface AttachmentInputs {
     config: {
         todoReminder: boolean;
         todoReminderMode?: "baseline" | "off";
+        toolSearchReminder?: boolean;
         changedFiles: boolean;
         planModeReminder: boolean;
         budgetUsd?: boolean;
@@ -86,6 +93,7 @@ export interface AttachmentInputs {
         skillsListing?: boolean;
         mcpInstructions?: boolean;
     };
+    undiscoveredTools?: readonly string[];
     changedFiles?: ReadonlyArray<{
         path: string;
         mtimeMs: number;
@@ -111,6 +119,7 @@ export interface AttachmentInputs {
     }>;
 }
 export declare function collectDueAttachments(state: AttachmentState, inp: AttachmentInputs): readonly TurnAttachment[];
+export declare function renderToolSearchUsageReminder(undiscovered: readonly string[]): string;
 export declare function renderDateChange(newDate: string): string;
 export declare function collectDateChange(state: DateChangeState, today: string): TurnAttachment | undefined;
 export declare function collectInstructionsChange(state: InstructionsChangeState, probed: ReadonlyArray<{
@@ -144,6 +153,7 @@ export interface McpToolsDeltaFacts {
 export declare function renderToolsDelta(input: {
     added?: readonly string[];
 } & McpToolsDeltaFacts): string | undefined;
+export declare const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
 export declare const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
 export declare const AMBIENT_CONTEXT_NOTE = "This is ambient context \u2014 do not narrate it to the user unless they ask or it is directly relevant to their request.";
 export declare function agentListingInitialHeader(toolName: string): string;

package/dist/core/runner/turn-attachments.js

@@ -10,6 +10,10 @@ export const PLAN_MODE_ATTACHMENT_CONFIG = {
     TURNS_BETWEEN_ATTACHMENTS: 5,
     FULL_REMINDER_EVERY_N_ATTACHMENTS: 5,
 };
+export const TOOL_SEARCH_REMINDER_CONFIG = {
+    EVERY_N_TURNS: 15,
+    MAX_NAMES: 10,
+};
 export const CHANGED_FILES_MAX = 20;
 export const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export const ATTACHMENT_BYTE_CAP = 8 * 1024;
@@ -20,6 +24,7 @@ export function createAttachmentState() {
     return {
         lastTodoReminderTurn: 0,
         lastTaskReminderTurn: 0,
+        lastToolSearchReminderTurn: 0,
         planAttachmentCount: 0,
         lastPlanReminderTurn: 0,
         surfacedMtime: new Map(),
@@ -84,6 +89,8 @@ export function reduceToolEnd(state, details) {
 export function stampWriteAnchor(state, family, clock) {
     if (family === "task")
         state.taskLastWriteTurn = clock;
+    else if (family === "tool_search")
+        state.toolSearchLastUseTurn = clock;
     else
         state.todoLastWriteTurn = clock;
 }
@@ -109,6 +116,8 @@ export function rebaseCadenceWindows(state, clock) {
     state.todoLastWriteTurn = clock;
     state.lastTaskReminderTurn = clock;
     state.lastTodoReminderTurn = clock;
+    state.toolSearchLastUseTurn = clock;
+    state.lastToolSearchReminderTurn = clock;
 }
 function countStatuses(items) {
     const counts = {};
@@ -138,6 +147,17 @@ export function collectDueAttachments(state, inp) {
             }
         }
     }
+    if (inp.config.toolSearchReminder &&
+        inp.undiscoveredTools !== undefined &&
+        inp.undiscoveredTools.length > 0 &&
+        !(out ?? []).some((a) => a.source === "todo_reminder" || a.source === "task_reminder")) {
+        const cadenceNow = inp.cadenceTurn ?? inp.turn;
+        const sinceUse = state.toolSearchLastUseTurn === undefined ? Number.POSITIVE_INFINITY : cadenceNow - state.toolSearchLastUseTurn;
+        if (sinceUse >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS && cadenceNow - state.lastToolSearchReminderTurn >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS) {
+            state.lastToolSearchReminderTurn = cadenceNow;
+            (out ??= []).push({ source: "tool_search_usage_reminder", body: renderToolSearchUsageReminder(inp.undiscoveredTools) });
+        }
+    }
     if (inp.config.planModeReminder && inp.planActive) {
         const due = state.planAttachmentCount === 0 ||
             inp.turn - state.lastPlanReminderTurn >= PLAN_MODE_ATTACHMENT_CONFIG.TURNS_BETWEEN_ATTACHMENTS;
@@ -228,6 +248,15 @@ function renderTaskReminder(state) {
     }
     return message;
 }
+export function renderToolSearchUsageReminder(undiscovered) {
+    const shown = undiscovered.slice(0, TOOL_SEARCH_REMINDER_CONFIG.MAX_NAMES);
+    const more = undiscovered.length - shown.length;
+    const names = `${shown.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
+    return (`Some available tools' schemas are not loaded in this conversation yet: ${names}. Before concluding a ` +
+        `capability is missing or building a workaround, use ${TOOL_SEARCH_TOOL_NAME} to find and load relevant tools — ` +
+        `keywords to search, or query "select:<name>[,<name>...]" for specific tools. Calling a tool before its schema ` +
+        `is loaded will fail. This is just a gentle reminder - ignore if not applicable to the current work.`);
+}
 export function renderDateChange(newDate) {
     return `The date has changed. Today's date is now ${newDate}. DO NOT mention this to the user explicitly because they are already aware.`;
 }
@@ -399,6 +428,7 @@ export function renderToolsDelta(input) {
     }
     return blocks.length > 0 ? blocks.join("\n\n") : undefined;
 }
+export const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
 export const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
 export const AMBIENT_CONTEXT_NOTE = "This is ambient context — do not narrate it to the user unless they ask or it is directly relevant to their request.";
 export function agentListingInitialHeader(toolName) {
@@ -451,7 +481,7 @@ export function agentListingDeltaHeader(toolName) {
 export function renderAgentListingDelta(state, entries, toolName, models) {
     const line = (e) => {
         const base = e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`;
-        return e.tools !== undefined ? `${base} (Tools: ${e.tools})` : base;
+        return `${base} (Tools: ${e.tools ?? AGENT_TOOLS_NOTE_DEFAULT})`;
     };
     const announced = state.announcedAgentTypes;
     if (announced === undefined) {
@@ -464,8 +494,8 @@ export function renderAgentListingDelta(state, entries, toolName, models) {
             blocks.push(modelsAvailableLine(models));
         return blocks.join("\n\n");
     }
-    const added = entries.filter((e) => !announced.has(e.name));
-    const removed = [...announced.keys()].filter((n) => !entries.some((e) => e.name === n));
+    const added = entries.filter((e) => !announced.has(e.name)).toSorted((a, b) => a.name.localeCompare(b.name));
+    const removed = [...announced.keys()].filter((n) => !entries.some((e) => e.name === n)).sort();
     const modelsDrifted = state.announcedModels !== undefined &&
         models !== undefined &&
         (state.announcedModels.length !== models.length || state.announcedModels.some((m, i) => m !== models[i]));

package/dist/core/task-registry-agent.d.ts

@@ -1,5 +1,6 @@
 import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
 import { type StopSource, type TaskAccess, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
+import { type ToolResultStore } from "./tool-result-store.js";
 export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
 export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: (keyof BackgroundAgentRecord)[]): void;
 export declare function durableAgentArmedLane(core: DurableAgentCore, id: string): boolean;
@@ -110,6 +111,15 @@ export declare function deliverToRunningAgentLane(core: DurableAgentCore, id: st
     reason: "not_found" | "not_running" | "no_channel";
 }>;
 export declare function runningBackgroundAgentLabelsLane(core: DurableAgentCore, access: TaskAccess): string[];
+export declare function runningAgentFooterLane(core: DurableAgentCore, access: TaskAccess): {
+    named: string[];
+    background: string[];
+};
+export declare function notFoundRunningAgentsTail(footer: {
+    named: string[];
+    background: string[];
+}): string;
 export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): UnifiedTaskResult;
-export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal): Promise<UnifiedTaskResult>;
+export declare function spillClippedAgentResult(handle: BackgroundAgentTaskHandle, full: string, clipped: string, store: ToolResultStore | undefined, sessionId: string | undefined): Promise<string>;
+export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal, oneShot?: boolean, store?: ToolResultStore, sessionId?: string): Promise<UnifiedTaskResult>;
 export declare function stopBackgroundAgentLane(core: DurableAgentCore, handle: BackgroundAgentTaskHandle): Promise<UnifiedTaskResult>;

package/dist/core/task-registry-agent.js

@@ -4,6 +4,7 @@ import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-a
 import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
 export function ensureDurableHeartbeatLane(core) {
     if (core.durableHeartbeatTimer !== undefined)
         return;
@@ -834,6 +835,7 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
         handle.abort = abort;
     handle.result = undefined;
     handle.resultFull = undefined;
+    handle.spillRef = undefined;
     handle.error = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
@@ -972,6 +974,24 @@ export function runningBackgroundAgentLabelsLane(core, access) {
     }
     return out;
 }
+export function runningAgentFooterLane(core, access) {
+    const named = [];
+    const background = [];
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
+            continue;
+        if (h.name !== undefined && h.name !== "") {
+            named.push(h.name);
+            continue;
+        }
+        background.push(h.description ? `${h.id} (${h.description})` : h.id);
+    }
+    return { named, background };
+}
+export function notFoundRunningAgentsTail(footer) {
+    return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
+        (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
+}
 export function serveDurableAgentRowLane(row) {
     if (row.status === "parked") {
         return {
@@ -1004,7 +1024,19 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
         },
     };
 }
-export async function pollBackgroundAgentLane(handle, deadline, signal) {
+export async function spillClippedAgentResult(handle, full, clipped, store, sessionId) {
+    if (clipped === full)
+        return clipped;
+    if (store === undefined)
+        return clipped;
+    if (handle.spillRef === undefined) {
+        const ref = buildToolResultRef(sessionId ?? "no-session", `${handle.id}_c${handle.reviveCycle ?? 0}`);
+        await store.put(ref, full);
+        handle.spillRef = ref;
+    }
+    return `${clipped}\n\n[full output persisted — call ${OFFLOAD_TOOL_NAME} with ref "${handle.spillRef}" to read it back.]`;
+}
+export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot, store, sessionId) {
     while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
         await sleepPollStep(deadline, signal);
     }
@@ -1023,13 +1055,18 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
             },
         };
     }
+    const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
+    const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
     const body = running
-        ? `status: running
+        ? oneShot === true
+            ? `status: running
+This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${handle.id}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.`
+            : `status: running
 The agent is still working — you will be notified when it completes.`
         : `status: ${handle.status}
 ${handle.error ? `error: ${handle.error}
 ` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
-${clipTaskOutput(handle.resultFull ?? handle.result, handle.outputFile)}` : "(no result text)"}`;
+${resultText}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
         details: {