apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-07 07:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity

fix(llm): allow StructuredOutput tool and raise maxTurns for generateObject

Browse source 
The Claude Code agent SDK announces an internal pseudo-tool named
StructuredOutput in the system/init message whenever outputFormat is set
to { type: 'json_schema' }. The runtime's isolation check built its
allowedToolIds set only from MCP tool ids and treated StructuredOutput
as an unexpected host-injected tool, so every generateObject call threw
"Claude Code runtime isolation failed: tools=StructuredOutput ..." and
the table-descriptions and relationship-LLM-proposal enrichment stages
recorded null output across the board.

Whitelist StructuredOutput specifically in generateObject's
allowedToolIds — the check also enforces missing_tools symmetry, so
generateText and runAgentLoop, which do not see StructuredOutput, must
not require it.

generateObject also ran with maxTurns: 1, which the model intermittently
breached when it emitted thinking text before the structured response.
Raised to 5 to give the schema-bound call enough headroom without
allowing unbounded loops. The existing tests now exercise the path with
an init message that announces StructuredOutput so the regression cannot
slip back in.
This commit is contained in:
Andrey Avtomonov 2026-05-23 10:37:08 +02:00
parent d8b2d8936f
commit 0cffb5b537
2 changed files with 25 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

14
packages/cli/src/context/llm/claude-code-runtime.test.ts
View file

@ -91,9 +91,14 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
});
});
it('validates structured output with the caller schema', async () => {
it('validates structured output with the caller schema and whitelists the SDK StructuredOutput tool', async () => {
const schema = z.object({ answer: z.string() });
const query = vi.fn((_input: any) => stream([initMessage(), resultMessage({ structured_output: { answer: 'yes' } })]));
const query = vi.fn((_input: any) =>
stream([
initMessage({ tools: ['StructuredOutput'] }),
resultMessage({ structured_output: { answer: 'yes' } }),
]),
);
const runtime = new ClaudeCodeKtxLlmRuntime({
projectDir: '/tmp/project',
modelSlots: { default: 'sonnet' },
@ -341,7 +346,10 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
it('passes scrubbed env to object generation and agent loops', async () => {
const schema = z.object({ answer: z.string() });
const objectQuery = vi.fn((_input: any) =>
stream([initMessage(), resultMessage({ structured_output: { answer: 'yes' } })]),
stream([
initMessage({ tools: ['StructuredOutput'] }),
resultMessage({ structured_output: { answer: 'yes' } }),
]),
);
const objectRuntime = new ClaudeCodeKtxLlmRuntime({
projectDir: '/tmp/project',

16
packages/cli/src/context/llm/claude-code-runtime.ts
View file

@ -47,6 +47,13 @@ const BUILTIN_TOOLS = [
const KTX_MCP_SERVER_NAME = 'ktx';
// SDK-internal pseudo-tool that the Claude Code CLI announces in its
// system/init message whenever outputFormat: { type: 'json_schema' } is set.
// Structured output is returned via result.structured_output (not through
// canUseTool), so the tool only needs to be whitelisted for generateObject's
// init isolation check; generateText / runAgentLoop never see it.
const STRUCTURED_OUTPUT_TOOL_NAME = 'StructuredOutput';
function isResult(message: SDKMessage): message is SDKResultMessage {
return message.type === 'result';
}
@ -238,7 +245,12 @@ export class ClaudeCodeKtxLlmRuntime implements KtxLlmRuntimePort {
projectDir: this.deps.projectDir,
model: modelForRole(this.deps.modelSlots, input.role),
env: this.deps.env,
maxTurns: 1,
// Structured output occasionally takes more than one assistant turn —
// the model may emit thinking/text before the StructuredOutput tool
// call, or the SDK may count assistant + tool-result as separate turns.
// 5 leaves headroom without enabling unbounded loops; the json_schema
// constraint still forces the final answer to be the schema.
maxTurns: 5,
tools: input.tools,
}),
outputFormat: { type: 'json_schema' as const, schema: jsonSchema(input.schema as z.ZodType) },
@ -247,7 +259,7 @@ export class ClaudeCodeKtxLlmRuntime implements KtxLlmRuntimePort {
query: this.runQuery,
prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
options,
allowedToolIds: new Set(mcpToolIds(input.tools ?? {})),
allowedToolIds: new Set([...mcpToolIds(input.tools ?? {}), STRUCTURED_OUTPUT_TOOL_NAME]),
expectedMcpServerNames: expectedMcpServerNames(input.tools),
});
const error = resultError(result);