@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/lib/capabilities/completion-engine/actors/preparing.js

@@ -1,25 +1,34 @@
-import { spliceFrom } from '../../../machine/index.js';
+import { Agent } from '../../../agent/index.js';
+import { spliceFrom } from '../splice.js';
 import { AbortedError } from '../../../helpers/race-abort.js';
-import { resolveLlmGenerationParams } from '../../../models/llm-presets.js';
-import { annotateLastUserTime, skillsPromptSection, systemPromptParts } from '../../../prompt.js';
-import { resolveImplicitSkill, resolveSkillMention } from '../../../tools/skills/mention.js';
-import { NETWORK_TOOLSETS, permittedTools } from '../../../tools/toolsets.js';
-import { explicitWebSearchQuery, lastUserContent, lastUserImages, sanitizeTurn, skillInContext, toSdkTool, selectEnabledTools } from '../../completion-loop/index.js';
-import { SKILL_TOOL_NAME } from '../../tool-names.js';
-import { collectToolGrants, isSelected, skillIsActive, skillsAreSelected } from '../../tool-selection.js';
+import { annotateLastUserTime, lastUserContent } from '../../../prompt.js';
+import { explicitWebSearchQuery, knowledgeLastUser, lastUserImages, modelTurns, preloadedSkillsFrom, withPromptContext } from '../turns.js';
+import { HookHalt } from '../../../helpers/engine-error.js';
+import { skillInContext } from '../../skill-entry.js';
+import { meetsMinCapabilityProfile, modelNameToCapabilityProfile } from '../../../models/model-catalog-constants.js';
+import { renderedTools, toSdkTools, withToolSearch } from '../../sdk-tool.js';
 import { loadedSkillFilesFrom, loadedSkillsFrom } from '../../tool-turns.js';
 import { promptPrefixHash } from '../../prompt-prefix.js';
 import { promptUsageParts } from '../../usage-breakdown.js';
 import { logToolPrompt } from '../../tool-prompt-log.js';
 import { toolContext } from './execution-plan.js';
+import { knowledgeSearch } from './retrieving.js';
 import { detachJson } from '../../../helpers/detach-json.js';
-export const preparing = async function preparing({ input, context, reconstruct }) {
+function offeredTools(tools, model) {
+    const profile = model ? modelNameToCapabilityProfile(model) : undefined;
+    return tools.filter(({ minCapabilityProfile: min }) => !min || (profile !== undefined && meetsMinCapabilityProfile(profile, min)));
+}
+export function preparing(source) {
+    return ({ input, context, reconstruct }) => prepare({ input, context, reconstruct, source });
+}
+async function prepare({ input, context, reconstruct, source }) {
     const { args, session } = input;
     const { model, agent, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, tools: allTools = [], skillCatalog = [], signal, fsRoots = [], fsWriteRoots = [] } = args;
     if (signal?.aborted) {
         throw new AbortedError();
     }
-    const messages = storedMessages.map(sanitizeTurn);
+    const messages = modelTurns(storedMessages, context.policy.continuationNudge);
+    let promptContext;
     if (!session.runStarted && !reconstruct) {
         await session.pipeline.onRunStart({
             runId: session.runId,
@@ -27,60 +36,48 @@ export const preparing = async function preparing({ input, context, reconstruct
             messages
         });
         session.runStarted = true;
+        const submitted = await session.pipeline.promptSubmit({
+            runId: session.runId,
+            agentId: agent?.id ?? null,
+            mode: 'prompt',
+            text: lastUserContent(messages)
+        });
+        if (!submitted.ok) {
+            throw new HookHalt(submitted.rejection.error, submitted.rejection.hook);
+        }
+        promptContext = submitted.context;
     }
-    const disabledToolsets = agent?.sandboxMode
-        ? [...(agent.disabledToolsets ?? []), ...NETWORK_TOOLSETS]
-        : agent?.disabledToolsets;
-    const tools = permittedTools(allTools, disabledToolsets);
-    const writableRoots = [
-        ...fsWriteRoots,
-        ...fsRoots.filter((root) => root.kind === 'hyper' && root.writable && !fsWriteRoots.includes(root))
-    ];
+    const hits = reconstruct ? [] : await knowledgeHits(input, context, messages);
     const turnImages = lastUserImages(messages);
-    const toolsSelected = isSelected(agent?.toolsScope, agent?.enabledTools);
-    const skillsSelected = skillsAreSelected(agent?.skillsScope, Boolean(agent));
-    const inContextSkills = skillCatalog.filter(skillInContext);
-    const mention = resolveSkillMention(lastUserContent(messages), inContextSkills);
     const loadedSkills = new Set([
         ...loadedSkillsFrom(messages),
-        ...(context.skills.snapshot?.loaded ?? [])
+        ...preloadedSkillsFrom(storedMessages),
+        ...context.activated
     ]);
     const loadedSkillFiles = loadedSkillFilesFrom(messages);
-    const activation = {
-        skillsSelected,
-        enabledSkills: agent?.enabledSkills ?? [],
-        mention: mention?.name ?? null,
-        loadedSkills
-    };
-    const activeSkills = inContextSkills.filter((skill) => skillIsActive(skill.name, activation));
-    const { grantedNames, grantedOwners, grantedOps } = collectToolGrants(activeSkills);
-    const selection = {
-        responseFormat: Boolean(responseFormat),
-        tools,
-        toolsSelected,
-        allowlist: agent?.enabledTools ?? [],
-        activeSkills,
-        grantedNames,
-        grantedOwners,
-        hasRoots: fsRoots.length > 0,
-        hasWriteRoots: writableRoots.length > 0
-    };
-    const enabled = selectEnabledTools({ ...selection, loadedSkills });
-    const sdkTools = enabled.length ? enabled.map((tool) => toSdkTool(tool)) : undefined;
-    const reasoningEnabled = settingEnabled(agent?.reasoning);
-    const deviceReasoning = settingEnabled(thinkingDefault);
-    const resolvedGenerationParams = resolveLlmGenerationParams(model, reasoningEnabled, deviceReasoning);
-    const generationParams = generationParamsOverride
-        ? { ...resolvedGenerationParams, ...generationParamsOverride }
-        : resolvedGenerationParams;
-    const system = systemPromptParts({
-        bio: agent?.bio,
-        toolNames: enabled.map((tool) => tool.name),
-        skillsSection: skillsPromptSection(activeSkills)
-    });
+    const inContextSkills = skillCatalog.filter(skillInContext);
+    const resolved = Agent.resolve({
+        agent,
+        model,
+        thinkingDefault,
+        generationParams: generationParamsOverride,
+        responseFormat,
+        messages,
+        tools: offeredTools(allTools, model),
+        skills: inContextSkills,
+        loadedSkills,
+        fsRoots,
+        fsWriteRoots,
+        planning: context.plan.length > 0 || context.goal !== null,
+        planMode: context.planMode
+    }, session.agentPorts);
+    const { system, activation, activeSkills, mention, grantedOps } = resolved;
+    const enabled = withToolSearch(resolved.enabled);
+    const sdkTools = toSdkTools(enabled);
+    const { skillsSelected } = activation;
     const systemContent = system.text;
     const promptPrefix = promptPrefixHash({ system: systemContent, tools: sdkTools });
-    const promptParts = promptUsageParts({ system, toolSchemas: sdkTools });
+    const promptParts = promptUsageParts({ system, toolSchemas: renderedTools(sdkTools) });
     const logSelection = (prefix) => {
         logToolPrompt({
             promptPrefix: prefix,
@@ -100,29 +97,34 @@ export const preparing = async function preparing({ input, context, reconstruct
         });
     };
     session.reselectTools = (loaded) => {
-        const reselected = selectEnabledTools({ ...selection, loadedSkills: loaded });
+        const reselected = withToolSearch(resolved.select(loaded));
         const names = reselected.map((tool) => tool.name).join();
         if (names === session.enabled.map((tool) => tool.name).join()) {
             return null;
         }
         session.enabled = reselected;
-        session.sdkTools = reselected.length ? reselected.map((tool) => toSdkTool(tool)) : undefined;
+        session.sdkTools = toSdkTools(reselected);
         const prefix = promptPrefixHash({ system: systemContent, tools: session.sdkTools });
-        session.promptParts = promptUsageParts({ system, toolSchemas: session.sdkTools });
+        session.promptParts = promptUsageParts({
+            system,
+            toolSchemas: renderedTools(session.sdkTools)
+        });
         logSelection(prefix);
         return prefix;
     };
-    const turns = messages;
+    const turns = withPromptContext(knowledgeLastUser(messages, hits), promptContext);
     const initialHistory = systemContent
         ? [{ role: 'system', content: systemContent }, ...turns]
         : turns;
     const history = context.round > 0 || context.directSearchDone
         ? [...context.history]
         : annotateLastUserTime(initialHistory, new Date(session.startedAt));
-    const sources = context.round > 0 || context.directSearchDone ? [...context.sources] : [];
+    const sources = context.round > 0 || context.directSearchDone
+        ? [...context.sources]
+        : hits.map((hit) => session.outbound.facts('tool-result', hit.text));
     const preparation = {
         history: spliceFrom(context.history, history),
-        loadedSkills: [...loadedSkills],
+        activated: [...loadedSkills],
         webSearches: context.webSearches,
         deniedKeys: [...context.deniedKeys],
         sources,
@@ -136,62 +138,44 @@ export const preparing = async function preparing({ input, context, reconstruct
         activation,
         inContextSkills,
         loadedSkillFiles,
-        writableRoots,
+        writableRoots: resolved.writableRoots,
         turnImages,
-        generationParams,
+        generationParams: resolved.generationParams,
         promptParts
     });
     logSelection(promptPrefix);
-    const round = {
-        preparation,
-        skillCandidate: null,
-        skillLoaderAvailable: false,
-        skillLoaderEffect: null,
-        skillAlreadyLoaded: false,
-        preload: null,
-        searchQuery: null
-    };
+    const round = { preparation, step: null, searchQuery: null };
     if (reconstruct) {
         return round;
     }
-    const preload = mention ?? resolveImplicitSkill(lastUserContent(messages), activeSkills);
-    const loader = enabled.find((tool) => tool.name === SKILL_TOOL_NAME);
-    const skillAlreadyLoaded = preload ? session.loadedThisTurn.has(preload.name) : false;
-    const skillLoaderEffect = preload && loader
-        ? loader.effect(detachJson({ name: preload.name }), toolContext({
-            deps: input,
-            context,
-            name: loader.name
-        }))
+    const call = source.propose(input, resolved);
+    const tool = call && enabled.find((tool) => tool.name === call.tool);
+    const effect = call && tool
+        ? tool.effect(detachJson(call.args), toolContext({ deps: input, context, name: tool.name }))
         : null;
     const searchQuery = (skillPreloaded) => context.directSearchDone
         ? null
         : explicitWebSearchQuery(lastUserContent(messages), enabled, { skillPreloaded });
     return {
         ...round,
-        skillCandidate: preload?.name ?? null,
-        skillLoaderAvailable: Boolean(loader),
-        skillLoaderEffect,
-        skillAlreadyLoaded,
-        preload: preload
-            ? {
-                ...preparation,
-                history: spliceFrom(context.history, initialHistory),
-                name: preload.name,
-                pendingSearch: searchQuery(true)
-            }
-            : null,
+        step: call && {
+            ...call,
+            available: Boolean(tool),
+            effect,
+            history: spliceFrom(context.history, initialHistory),
+            pendingSearch: searchQuery(true)
+        },
         searchQuery: searchQuery(false)
     };
-};
-function settingEnabled(value) {
-    if (value === 'enabled') {
-        return true;
-    }
-    if (value === 'disabled') {
-        return false;
+}
+function knowledgeHits(deps, context, messages) {
+    if (context.round > 0 || context.directSearchDone) {
+        return Promise.resolve([]);
     }
-    return undefined;
+    return knowledgeSearch(deps, {
+        id: `${context.runId}:round-${context.round}:prepare:knowledge`,
+        text: Agent.untransferred(lastUserContent(messages))
+    });
 }
 function prepareSession(session, prepared) {
     Object.assign(session, prepared);

package/dist-lib/lib/capabilities/completion-engine/actors/rejecting.d.ts

@@ -1,3 +1,3 @@
-import { type ToolDonePayload } from '../../../machine/index.ts';
 import type { CompletionActor } from '../session.ts';
+import type { ToolDonePayload } from '../stages.ts';
 export declare const rejecting: CompletionActor<ToolDonePayload>;

package/dist-lib/lib/capabilities/completion-engine/actors/rejecting.js

@@ -1,17 +1,33 @@
-import { readFailureResult, spliceFrom } from '../../../machine/index.js';
-import { directToolHistory, labelOf } from '../../completion-loop/index.js';
+import { spliceFrom } from '../splice.js';
+import { directToolHistory } from '../turns.js';
+import { labelOf } from '../loop.js';
 import { toolResultHistoryEntry, toolResultTurn } from '../../tool-turns.js';
-import { trustedSourceFacts } from '../../../tools/outbound-guard.js';
+import { readFailureResult, storeFailureResult } from '../../../helpers/failure-result.js';
+import { reportFailure } from '../tool-execution.js';
 export const rejecting = async function rejecting({ emit, input: { session }, context }) {
     const rejected = context.rejectedCall;
     if (!rejected) {
         throw new Error('completion graph selected rejection without a rejected call');
     }
     const { call } = rejected;
-    const result = rejected.resultRef
+    const refused = rejected.resultRef
         ? failureResult(context, rejected.resultRef, call.name)
         : rejected.result;
-    session.runOutcomes.record(result, rejected.repeat ?? rejected.outcome ?? { kind: 'blocked', reason: 'Tool call was rejected' });
+    const outcome = rejected.repeat ??
+        rejected.outcome ?? { kind: 'blocked', reason: 'Tool call was rejected' };
+    const result = rejected.repeat
+        ? refused
+        : await reportFailure(session.pipeline, {
+            runId: session.runId,
+            callId: call.id,
+            toolName: call.name,
+            agentId: context.agentId,
+            args: call.args,
+            executed: false,
+            outcome,
+            result: refused
+        });
+    session.runOutcomes.record(result, outcome);
     if (rejected.emitCall) {
         emit({
             type: 'tool-call',
@@ -44,7 +60,8 @@ export const rejecting = async function rejecting({ emit, input: { session }, co
         ? {
             key: call.key,
             resultRef: requiredFailureRef(rejected.resultRef),
-            outcome: rejected.outcome
+            outcome: rejected.outcome,
+            value: result === refused ? undefined : { name: call.name, result: storeFailureResult(result) }
         }
         : undefined;
     return {
@@ -53,7 +70,7 @@ export const rejecting = async function rejecting({ emit, input: { session }, co
         searchCapped: rejected.capped,
         blockedRepeat: rejected.repeat ? true : undefined,
         history: spliceFrom(context.history, history),
-        source: trustedSourceFacts(rejected.source, turn)
+        source: session.outbound.facts(rejected.source, turn)
     };
 };
 function failureResult(context, ref, name) {

package/dist-lib/lib/capabilities/completion-engine/actors/rejection.d.ts

@@ -1,4 +1,6 @@
-import { type CompletionMachineContext as CompletionContext, type ResolvedCallSnapshot, type ResourceDescriptor, type ToolActivityEvent, type ToolEffect, type ToolExecutionSnapshot, type ToolRejection } from '../../../machine/index.ts';
+import { type CompletionContext } from '../../../machine/index.ts';
+import type { ResolvedCallSnapshot, ToolExecutionSnapshot, ToolRejection } from '../stages.ts';
+import type { ResourceDescriptor, ToolActivityEvent, ToolEffect } from '../../../contract/index.ts';
 interface PolicyActivityInput {
     call: ResolvedCallSnapshot;
     effect: ToolEffect | undefined;
@@ -13,6 +15,6 @@ export interface GateRejectionInput {
     resource: ResourceDescriptor | null;
     source: ToolRejection['source'];
 }
-export declare function gateRejection({ call, execution, resource, source }: GateRejectionInput): ToolRejection | undefined;
+export declare function gateRejection({ context, call, execution, resource, source }: GateRejectionInput): ToolRejection | undefined;
 export declare function deniedWithoutApprover({ context, call, execution, source }: GateRejectionInput): ToolRejection | undefined;
 export {};

package/dist-lib/lib/capabilities/completion-engine/actors/rejection.js

@@ -1,4 +1,5 @@
-import { TOOL_DENIED_MESSAGE, toolDeniedResult } from '../../../machine/index.js';
+import { CompletionMachine } from '../../../machine/index.js';
+import { toolDeniedResult } from '../../../helpers/failure-result.js';
 export function policyActivity({ call, effect, resource, decision = 'blocked' }) {
     return {
         type: 'tool-activity',
@@ -9,7 +10,7 @@ export function policyActivity({ call, effect, resource, decision = 'blocked' })
         decision
     };
 }
-export function gateRejection({ call, execution, resource, source }) {
+export function gateRejection({ context, call, execution, resource, source }) {
     const facts = execution?.gate?.facts;
     if (!facts) {
         return undefined;
@@ -35,8 +36,8 @@ export function gateRejection({ call, execution, resource, source }) {
     }
     if (facts.deniedKey) {
         return {
-            result: toolDeniedResult(),
-            outcome: { kind: 'denied', reason: TOOL_DENIED_MESSAGE },
+            result: toolDeniedResult(context.policy.deniedMessage),
+            outcome: { kind: 'denied', reason: context.policy.deniedMessage },
             activity: null,
             effect,
             source
@@ -50,13 +51,12 @@ export function deniedWithoutApprover({ context, call, execution, source }) {
     if (!gate || !facts) {
         return undefined;
     }
-    const autoRuns = facts.effect === 'read' || facts.autoApprove || facts.skipApprovals;
-    if (autoRuns || context.approval.status !== 'idle' || gate.approver) {
+    if (CompletionMachine.runsUnasked(facts) || context.approval.status !== 'idle' || gate.approver) {
         return undefined;
     }
     return {
-        result: toolDeniedResult(),
-        outcome: { kind: 'denied', reason: TOOL_DENIED_MESSAGE },
+        result: toolDeniedResult(context.policy.deniedMessage),
+        outcome: { kind: 'denied', reason: context.policy.deniedMessage },
         activity: policyActivity({
             call,
             effect: facts.effect,

package/dist-lib/lib/capabilities/completion-engine/actors/resolving.d.ts

@@ -1,3 +1,3 @@
 import type { CompletionActor } from '../session.ts';
-import type { ResolvingOutput } from '../../../machine/index.ts';
+import type { ResolvingOutput } from '../stages.ts';
 export declare const resolving: CompletionActor<ResolvingOutput>;

package/dist-lib/lib/capabilities/completion-engine/actors/resolving.js

@@ -1,10 +1,25 @@
-import { spliceFrom } from '../../../machine/index.js';
+import { Agent } from '../../../agent/index.js';
+import { spliceFrom } from '../splice.js';
 import { AbortedError } from '../../../helpers/race-abort.js';
 import { hlog } from '../../../log.js';
-import { stripToolCallMarkup } from '../../../helpers/tool-call-markup.js';
-import { assistantToolTurn, resolveToolCalls } from '../../completion-loop/index.js';
+import { MALFORMED_CALL_ID, stripToolCallMarkup } from '../../../helpers/tool-call-markup.js';
+import { toolResultTurn } from '../../tool-turns.js';
+import { unloadedTools } from '../../sdk-tool.js';
+import { assistantToolTurn } from '../turns.js';
+import { resolveToolCalls } from '../tool-execution.js';
+import { toolContext } from './execution-plan.js';
+import { detachJson } from '../../../helpers/detach-json.js';
+const REISSUE_HINT = 'Re-issue the tool call with complete, valid markup.';
 const NARRATED_INTENT = /\b(I['’]ll|I will|Now I|Let me(?! know)|Next,? I)\b[^.!?]*[.!?]?\s*$/i;
-export const resolving = async function resolving({ input: { args, session }, context }) {
+const CODE = /```[\s\S]*?(?:```|$)|`[^`\n]*`/g;
+const QUESTION = /\?(?![\w=&%/])/;
+const ASKS = /\bplease\s+(?:provide|tell|give|share|send|specify|confirm|let me know)\b|\b(?:tell|send|show)\s+me\b|\bgive\s+me\b(?!\s+(?:just\s+)?(?:a|an|one|two|\d+|a few|a couple(?:\s+of)?|some)\s+(?:moment|sec(?:ond)?|minute|min|bit|while|tick)s?\s*(?:[,.;!…—–]|\s-|$|(?:to|while|and|so|as|then)\b))|\blet me know\b/i;
+function narratedIntent(spoken) {
+    const prose = spoken.replace(CODE, '');
+    return NARRATED_INTENT.test(spoken) && !QUESTION.test(prose) && !ASKS.test(prose);
+}
+export const resolving = async function resolving({ input: deps, context }) {
+    const { args, session } = deps;
     const round = context.lastRound;
     const toolCalls = round.toolCalls.map((call) => ({
         id: call.id,
@@ -13,31 +28,63 @@ export const resolving = async function resolving({ input: { args, session }, co
         raw: call.raw
     }));
     if (!toolCalls.length) {
-        return answerFacts({ round, roundNumber: context.round, session });
+        return answerFacts({ round, context, session });
     }
     const resolved = await resolveToolCalls(toolCalls, session.enabled, {
         runId: session.runId,
-        agentId: args.agent?.id ?? null,
+        agentId: context.agentId,
         pipeline: session.pipeline,
         skillNames: session.inContextSkills.map((skill) => skill.name),
-        sandboxMode: args.agent?.sandboxMode === true,
+        sandboxMode: session.policy.sandbox,
+        toolContext: (name) => toolContext({ deps, context, name }),
         signal: args.signal
     });
     if (args.signal?.aborted) {
         throw new AbortedError();
     }
-    return resolvedOutput({ context, round, resolved, session });
+    return resolvedOutput({ context, round, resolved, deps });
 };
-function answerFacts({ round, roundNumber, session }) {
+function answerFacts({ round, context, session }) {
     const replay = round.replay ? stripToolCallMarkup(round.replay) : '';
     const spoken = round.contentText.trim();
-    const narrated = session.enabled.length && !replay && NARRATED_INTENT.test(spoken) ? spoken : undefined;
+    const narrated = session.enabled.length && !replay && narratedIntent(spoken) ? spoken : undefined;
     if (narrated) {
-        hlog('round narrated a tool call', { round: roundNumber });
+        hlog('round narrated a tool call', { round: context.round });
+    }
+    const answer = { calls: [], response: replay || round.contentText, narrated };
+    if (!round.toolErrors?.length) {
+        return answer;
     }
-    return { calls: [], response: replay || round.contentText, narrated };
+    hlog('round made malformed tool calls', {
+        round: context.round,
+        errors: round.toolErrors.map((error) => error.code)
+    });
+    return { ...answer, history: malformedCallTurns({ round, context, session }), malformed: true };
+}
+function malformedCallTurns({ round, context, session }) {
+    const errors = round.toolErrors ?? [];
+    const said = [round.contentText.trim(), ...errors.map((error) => error.raw ?? '')];
+    const error = round.stopReason === 'length'
+        ? context.policy.cutOffMessage
+        : [
+            ...errors.map(({ code, message }) => `${code}: ${message}`),
+            reissueHint(errors, unloadedTools(session.enabled, context.history))
+        ].join('\n');
+    return spliceFrom(context.history, [
+        ...context.history,
+        { role: 'assistant', content: said.filter(Boolean).join('\n') },
+        { role: 'tool', content: toolResultTurn('tool_call', MALFORMED_CALL_ID, { error }) },
+        { role: 'user', content: context.policy.continuationNudge }
+    ]);
+}
+function reissueHint(errors, unloaded) {
+    const named = [...unloaded].filter((name) => errors.some(({ code, message }) => code === 'UNKNOWN_TOOL' && message.includes(`"${name}"`)));
+    return named.length
+        ? `Load ${named.join(', ')} first: call tool_search with the tool's name, then call the tool.`
+        : REISSUE_HINT;
 }
-function resolvedOutput({ context, round, resolved, session }) {
+function resolvedOutput({ context, round, resolved, deps }) {
+    const { session } = deps;
     const history = [
         ...context.history,
         {
@@ -46,14 +93,25 @@ function resolvedOutput({ context, round, resolved, session }) {
         }
     ];
     return {
-        calls: resolved.map(({ call, args: callArgs, rawCall, intent, rejection }) => ({
+        calls: resolved.map(({ call, tool, args: callArgs, rawCall, intent, rejection, permission }) => ({
             id: call.id,
             key: session.callKey(call.name, callArgs),
             name: call.name,
             args: callArgs,
             rawCall,
             intent,
-            rejection
+            rejection,
+            permission,
+            concurrent: tool?.concurrent &&
+                !tool.endsRun &&
+                !rejection &&
+                tool.effect(detachJson(callArgs), toolContext({ deps, context, name: tool.name })) ===
+                    'read'
+                ? true
+                : undefined,
+            leavesPlan: context.planMode && tool?.name === Agent.PLAN_TOOL_NAME && callArgs.submit === true
+                ? true
+                : undefined
         })),
         history: spliceFrom(context.history, history)
     };

package/dist-lib/lib/capabilities/completion-engine/actors/retrieving.d.ts

@@ -0,0 +1,10 @@
+import type { KnowledgeHit } from '../../../contract/knowledge.ts';
+import type { CompletionActor, CompletionDeps } from '../session.ts';
+import type { RetrievingOutput } from '../stages.ts';
+export declare const retrieving: CompletionActor<RetrievingOutput>;
+interface KnowledgeSearch {
+    id: string;
+    text: string;
+}
+export declare function knowledgeSearch({ args, services, operations }: CompletionDeps, { id, text }: KnowledgeSearch): Promise<KnowledgeHit[]>;
+export {};

package/dist-lib/lib/capabilities/completion-engine/actors/retrieving.js

@@ -0,0 +1,56 @@
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { isFailureResultReference } from '../../../helpers/failure-result.js';
+import { hlog } from '../../../log.js';
+import { errorMessage } from '../../../guards.js';
+import { spliceFrom } from '../splice.js';
+import { knowledgeLastUser } from '../turns.js';
+export const retrieving = async function retrieving({ input, context }) {
+    const { history } = context;
+    const at = history.findLastIndex((entry) => !isFailureResultReference(entry) && entry.role === 'user');
+    const turn = history[at];
+    if (!turn || isFailureResultReference(turn)) {
+        return {};
+    }
+    const hits = await knowledgeSearch(input, {
+        id: `${context.runId}:round-${context.round}:input:knowledge`,
+        text: turn.content
+    });
+    if (hits.length === 0) {
+        return {};
+    }
+    const next = [...history];
+    next[at] = knowledgeLastUser([turn], hits)[0];
+    return {
+        history: spliceFrom(history, next),
+        sources: hits.map((hit) => input.session.outbound.facts('tool-result', hit.text))
+    };
+};
+export function knowledgeSearch({ args, services, operations }, { id, text }) {
+    const knowledge = services?.knowledge;
+    const scopes = args.knowledge?.scopes ?? [];
+    const query = text.trim();
+    if (!knowledge ||
+        scopes.length === 0 ||
+        !query ||
+        args.agent?.disabledToolsets?.includes('knowledge')) {
+        return Promise.resolve([]);
+    }
+    const search = async () => {
+        try {
+            return await knowledge.search({ text: query, scopes, signal: args.signal });
+        }
+        catch (error) {
+            if (args.signal?.aborted || error instanceof AbortedError) {
+                throw error;
+            }
+            hlog('knowledge search failed', { err: errorMessage(error) });
+            return [];
+        }
+    };
+    return operations.operation({
+        id,
+        name: 'knowledge:search',
+        args: { scopes: [...scopes].sort() },
+        effect: 'read'
+    }, search, undefined, args.signal);
+}

package/dist-lib/lib/capabilities/completion-engine/actors/run-prepare.d.ts

@@ -0,0 +1,4 @@
+import type { PrepareStepSource } from '../prepare-step.ts';
+import type { CompletionActor } from '../session.ts';
+import type { PrepareRunOutput } from '../stages.ts';
+export declare function runPrepare(source: PrepareStepSource): CompletionActor<PrepareRunOutput>;