Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 68 additions & 2 deletions src/agents/AgentContext.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,9 @@ import {
Providers,
} from '@/common';
import { isTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
import { normalizeToBashIdentifier } from '@/tools/BashProgrammaticToolCalling';
import { snapshotCompactionSemanticIndex } from '@/summarization/semanticIndex';
import { normalizeToPythonIdentifier } from '@/tools/ProgrammaticToolCalling';
import { createExactTokenCountCache } from '@/llm/contextPressureMeter';
import { markProviderTextInput } from '@/protection/providerTextInput';
import { buildSummaryCarrierText } from '@/summarization/shared';
Expand All @@ -81,6 +83,7 @@ type PromptCacheProvider = Providers.ANTHROPIC | Providers.OPENROUTER;
type ProgrammaticToolInstructionTarget = {
name: string;
codeGuidance: string;
runtimes: Array<'Bash' | 'Python'>;
executesDirectly: boolean;
};

Expand Down Expand Up @@ -680,12 +683,73 @@ export class AgentContext {
.map((name) => `\`${name}\``)
.join(
', '
)}. Every ${programmaticRunnerNames} call must include a \`tool_manifest\` containing the exact registered names used by its code; the manifest is validated before execution starts.`
)}. Every ${programmaticRunnerNames} call must include a \`tool_manifest\` containing the registered names or sandbox names used by its code; the manifest is validated before execution starts.`
: '';
const runtimes = new Set(
programmaticTools.flatMap((tool) => tool.runtimes)
);
const identifierOwners = new Map<string, string | null>();
for (const runtime of runtimes) {
const normalizeIdentifier =
runtime === 'Bash'
? normalizeToBashIdentifier
: normalizeToPythonIdentifier;
for (const toolDefs of [
capabilities.codeExecutionTools,
capabilities.directOnlyTools,
]) {
for (const toolDef of toolDefs) {
const key = `${runtime}:${normalizeIdentifier(toolDef.name)}`;
const owner = identifierOwners.get(key);
identifierOwners.set(
key,
owner === undefined || owner === toolDef.name ? toolDef.name : null
);
}
}
}
const sandboxNames: string[] = [];
const collidingNames: string[] = [];
for (const toolDef of capabilities.codeExecutionTools) {
const names: string[] = [];
const collisions: string[] = [];
for (const runtime of runtimes) {
const identifier =
runtime === 'Bash'
? normalizeToBashIdentifier(toolDef.name)
: normalizeToPythonIdentifier(toolDef.name);
if (identifier === toolDef.name) {
continue;
}
if (identifierOwners.get(`${runtime}:${identifier}`) !== toolDef.name) {
collisions.push(`${runtime} code \`${identifier}\``);
} else {
names.push(`${runtime} \`${identifier}\``);
}
}
if (names.length > 0) {
sandboxNames.push(`- \`${toolDef.name}\`: ${names.join('; ')}`);
}
if (collisions.length > 0) {
collidingNames.push(`- \`${toolDef.name}\`: ${collisions.join('; ')}`);
}
}
const sandboxNameGuidance =
sandboxNames.length === 0
? ''
: '\n\nUse sandbox names in both code and `tool_manifest` for the tools below; registered names are also accepted in `tool_manifest`:\n' +
sandboxNames.join('\n');
const collidingNameGuidance =
collidingNames.length === 0
? ''
: '\n\nFor colliding sandbox names, use registered names in `tool_manifest` and sandbox names in code. Select only one tool per sandbox name:\n' +
collidingNames.join('\n');
const boundary =
'\n\n' +
`Only these tools may be invoked inside ${programmaticRunnerNames}: ${quotedProgrammaticNames}.` +
directOnlyBoundary;
directOnlyBoundary +
sandboxNameGuidance +
collidingNameGuidance;

if (programmaticOnlyTools.length === 0) {
return boundary;
Expand Down Expand Up @@ -730,6 +794,7 @@ export class AgentContext {
targets.push({
name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
codeGuidance: 'Bash code',
runtimes: ['Bash'],
executesDirectly: this.isProgrammaticRunnerDirectlyBound(
Constants.BASH_PROGRAMMATIC_TOOL_CALLING
),
Expand All @@ -751,6 +816,7 @@ export class AgentContext {
codeGuidance: localDefault
? 'Bash code by default, or set `lang: "py"` to use Python code'
: 'Python code',
runtimes: localDefault ? ['Bash', 'Python'] : ['Python'],
executesDirectly: this.isProgrammaticRunnerDirectlyBound(
Constants.PROGRAMMATIC_TOOL_CALLING
),
Expand Down
94 changes: 94 additions & 0 deletions src/agents/__tests__/AgentContext.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1194,6 +1194,100 @@ describe('AgentContext', () => {
expect(result[0].content).not.toContain('run_tools_with_bash');
});

it.each([
[Constants.BASH_PROGRAMMATIC_TOOL_CALLING, 'Bash'],
[Constants.PROGRAMMATIC_TOOL_CALLING, 'Python'],
])('shows sandbox names for %s', async (runnerName, runtime) => {
const ctx = createBasicContext({
agentConfig: {
instructions: 'Base',
toolDefinitions: [{ name: runnerName }],
toolRegistry: new Map([
[
'stub_echo_mcp_hypen-server',
{
name: 'stub_echo_mcp_hypen-server',
allowed_callers: ['code_execution'],
},
],
[
'both_mcp_my-server',
{
name: 'both_mcp_my-server',
allowed_callers: ['direct', 'code_execution'],
},
],
['direct_only', { name: 'direct_only' }],
]),
},
});

const result = await ctx.systemRunnable!.invoke([]);
const content = String(result[0].content);
expect(content).toContain(
'Use sandbox names in both code and `tool_manifest`'
);
expect(content).toContain(
`\`stub_echo_mcp_hypen-server\`: ${runtime} \`stub_echo_mcp_hypen_server\``
);
expect(content).toContain(
`\`both_mcp_my-server\`: ${runtime} \`both_mcp_my_server\``
);
expect(content).toContain(
'registered names are also accepted in `tool_manifest`'
);
});

it.each([
[Constants.BASH_PROGRAMMATIC_TOOL_CALLING, 'Bash', 'code_execution'],
[Constants.PROGRAMMATIC_TOOL_CALLING, 'Python', 'code_execution'],
[Constants.BASH_PROGRAMMATIC_TOOL_CALLING, 'Bash', 'direct'],
[Constants.PROGRAMMATIC_TOOL_CALLING, 'Python', 'direct'],
] as const)(
'uses registered manifests for %s (%s, other caller: %s)',
async (runnerName, runtime, otherCaller) => {
const registeredName = 'delete_record_mcp_prod-server';
const sandboxName = 'delete_record_mcp_prod_server';
const ctx = createBasicContext({
agentConfig: {
toolDefinitions: [{ name: runnerName }],
toolRegistry: new Map([
[
registeredName,
{
name: registeredName,
allowed_callers: ['code_execution'],
},
],
[
sandboxName,
{
name: sandboxName,
allowed_callers: [otherCaller],
},
],
]),
},
});

const content = String(
(await ctx.systemRunnable!.invoke([]))[0].content
);
expect(content).toContain(
'For colliding sandbox names, use registered names in `tool_manifest` and sandbox names in code. Select only one tool per sandbox name'
);
expect(content).toContain(
`- \`${registeredName}\`: ${runtime} code \`${sandboxName}\``
);
expect(content).not.toContain(
`- \`${registeredName}\`: ${runtime} \`${sandboxName}\``
);
expect(content).not.toContain(
'Use sandbox names in both code and `tool_manifest`'
);
}
);

it('makes mixed direct and programmatic caller boundaries explicit', async () => {
const toolRegistry: t.LCToolRegistry = new Map([
[
Expand Down
7 changes: 5 additions & 2 deletions src/tools/BashProgrammaticToolCalling.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ import {
runPlainExecution,
formatCompletedResponse,
} from './ProgrammaticToolCalling';
import { logCodeApiDiagnostic } from '@/tools/diagnostics';
import { resolveAttachedWorkspaceInstanceId } from '@/tools/workspaceIdentity';
import { logCodeApiDiagnostic } from '@/tools/diagnostics';
import { INTENT_PROPERTY } from '@/tools/intentArg';
import { Constants } from '@/common';

Expand Down Expand Up @@ -155,7 +155,9 @@ ${EXAMPLES}
${CORE_RULES}`;

const TOOL_MANIFEST_DESCRIPTION =
'Exact registered tool names used by the code. Required when direct-only tools are configured; ' +
'Registered tool names or their normalized sandbox function names used by the code. ' +
'Use sandbox names in code, but registered names in tool_manifest when sandbox names collide. ' +
'Required when direct-only tools are configured; ' +
'validated before execution starts. Pass [] when the code calls no tools at all.';

// ============================================================================
Expand Down Expand Up @@ -433,6 +435,7 @@ export function createBashProgrammaticToolCallingTool(
allowedToolDefs: toolDefs,
disallowedToolDefs,
programmaticToolName,
normalizeIdentifier: normalizeToBashIdentifier,
});

/* These guard the replay path only. A call that selected no tools never
Expand Down
45 changes: 42 additions & 3 deletions src/tools/ProgrammaticCallerPolicy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ export function selectProgrammaticTools(args: {
allowedToolDefs?: t.LCTool[];
disallowedToolDefs?: t.LCTool[];
programmaticToolName: string;
normalizeIdentifier?: (name: string) => string;
}): t.LCTool[] {
const allowedToolDefs = args.allowedToolDefs ?? [];
const disallowedToolDefs = args.disallowedToolDefs ?? [];
Expand Down Expand Up @@ -111,6 +112,42 @@ export function selectProgrammaticTools(args: {
const unknownNames = new Set(
requestedToolNames.filter((name) => !allowedByName.has(name))
);
if (unknownNames.size > 0 && args.normalizeIdentifier != null) {
const candidatesByIdentifier = new Map<string, t.LCTool[]>();
for (const toolDef of allowedToolDefs) {
const identifier = args.normalizeIdentifier(toolDef.name);
if (!unknownNames.has(identifier)) {
continue;
}
const candidates = candidatesByIdentifier.get(identifier) ?? [];
candidates.push(toolDef);
candidatesByIdentifier.set(identifier, candidates);
}

const disallowedAliases = new Set<string>();
for (const toolDef of disallowedToolDefs) {
const identifier = args.normalizeIdentifier(toolDef.name);
if (unknownNames.has(identifier)) {
disallowedAliases.add(toolDef.name);
}
}
assertDisallowedToolUsage(disallowedAliases, args.programmaticToolName);

for (const name of unknownNames) {
const candidates = candidatesByIdentifier.get(name);
if (candidates == null) {
continue;
}
assertUnambiguousIdentifiers(
candidates,
args.normalizeIdentifier,
args.programmaticToolName
);
allowedByName.set(name, candidates[0]);
unknownNames.delete(name);
}
}

if (unknownNames.size > 0) {
throw new Error(
`Tool${unknownNames.size === 1 ? '' : 's'} ${[...unknownNames]
Expand All @@ -122,7 +159,9 @@ export function selectProgrammaticTools(args: {
);
}

return [...new Set(requestedToolNames)].map(
(name) => allowedByName.get(name) as t.LCTool
);
return [
...new Set(
requestedToolNames.map((name) => allowedByName.get(name) as t.LCTool)
),
];
}
5 changes: 4 additions & 1 deletion src/tools/ProgrammaticToolCalling.ts
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,9 @@ ${EXAMPLES}
${CORE_RULES}`;

const TOOL_MANIFEST_DESCRIPTION =
'Exact registered tool names used by the code. Required when direct-only tools are configured; ' +
'Registered tool names or their normalized sandbox function names used by the code. ' +
'Use sandbox names in code, but registered names in tool_manifest when sandbox names collide. ' +
'Required when direct-only tools are configured; ' +
'validated before execution starts. Pass [] when the code calls no tools at all.';

export function createProgrammaticToolCallingSchema(
Expand Down Expand Up @@ -1127,6 +1129,7 @@ export function createProgrammaticToolCallingTool(
allowedToolDefs: toolDefs,
disallowedToolDefs,
programmaticToolName,
normalizeIdentifier: normalizeToPythonIdentifier,
});

/* These guard the replay path only. A call that selected no tools never
Expand Down
40 changes: 40 additions & 0 deletions src/tools/__tests__/ProgrammaticPlainExecution.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,46 @@ describe('behavior that stays as it was', () => {
});
});

describe.each([
['Bash', invokeBash],
['Python', invokePython],
])('%s sandbox-name manifests', (_runtime, invokeTool) => {
beforeEach(() => {
requests.length = 0;
});

it.each(['stub_echo_mcp_hypen-server', 'stub_echo_mcp_hypen_server'])(
'sends the original registered definition for %s',
async (manifestName) => {
const definition: t.LCTool = {
name: 'stub_echo_mcp_hypen-server',
allowed_callers: ['code_execution'],
};
await invokeTool(
{ code: 'stub_echo_mcp_hypen_server', tool_manifest: [manifestName] },
{
toolMap: new Map([[definition.name, createCalculatorTool()]]),
toolDefs: [definition],
disallowedToolDefs: [{ name: 'direct_only' }],
}
);

expect(requests).toHaveLength(1);
expect(requests[0].body.tools).toEqual([definition]);
}
);

it('rejects normalized direct-only names before sending a request', async () => {
await expect(
invokeTool(
{ code: 'send_email', tool_manifest: ['send_email'] },
{ ...DEFAULT_CONTEXT, disallowedToolDefs: [{ name: 'send-email' }] }
)
).rejects.toThrow('not marked for code_execution');
expect(requests).toHaveLength(0);
});
});

describe('ambiguous runtime identifiers', () => {
const colliding: t.LCTool[] = [
{ name: 'report-tool', allowed_callers: ['code_execution'] },
Expand Down
Loading
Loading