@kaelio/ktx 0.13.1 → 0.15.0

package/dist/context/ingest/tools/read-raw-span.tool.js

@@ -1,9 +1,13 @@
 import { readFile } from 'node:fs/promises';
-import { join, normalize, resolve } from 'node:path';
+import { isAbsolute, join, normalize, relative, resolve } from 'node:path';
 import { tool } from 'ai';
 import { z } from 'zod';
+function normalizeRawPath(path) {
+    return normalize(path).replace(/^[/\\]+/, '').replace(/\\/g, '/');
+}
 export function createReadRawSpanTool(deps) {
     const stagedRoot = resolve(deps.stagedDir);
+    const allowedPaths = new Set([...deps.allowedPaths].map(normalizeRawPath));
     return tool({
         description: 'Read a 1-based inclusive line range from a raw source file. Use this to resolve a provenance pointer like `file.lkml#L15-28` without loading the whole file into context.',
         inputSchema: z.object({
@@ -15,12 +19,13 @@ export function createReadRawSpanTool(deps) {
             if (startLine > endLine) {
                 return `Error: startLine must be <= endLine (got startLine=${startLine}, endLine=${endLine})`;
             }
-            const normalized = normalize(path).replace(/^[/\\]+/, '');
-            if (normalized.startsWith('..') || !deps.allowedPaths.has(normalized)) {
-                return `Error: path "${path}" is not accessible from this context. Allowed paths: ${[...deps.allowedPaths].sort().join(', ')}`;
+            const normalized = normalizeRawPath(path);
+            if (normalized.startsWith('..') || !allowedPaths.has(normalized)) {
+                return `Error: path "${path}" is not accessible from this context. Allowed paths: ${[...allowedPaths].sort().join(', ')}`;
             }
             const absolute = resolve(join(stagedRoot, normalized));
-            if (!absolute.startsWith(`${stagedRoot}/`) && absolute !== stagedRoot) {
+            const stagedRelative = relative(stagedRoot, absolute);
+            if (stagedRelative.startsWith('..') || isAbsolute(stagedRelative)) {
                 return `Error: path "${path}" is not accessible from this context.`;
             }
             try {

package/dist/context/ingest/tools/warehouse-verification/discover-data.tool.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { BaseTool } from '../../../../context/tools/base-tool.js';
 const discoverDataInputSchema = z.object({
     query: z.string().optional(),
-    connectionId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/).optional(),
+    connectionId: z.string().regex(/^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/).optional(),
     limit: z.number().int().positive().max(50).optional().default(10),
     sourceName: z.string().optional(),
 }).strict();

package/dist/context/ingest/tools/warehouse-verification/entity-details.tool.js

@@ -10,7 +10,7 @@ const targetSchema = z.union([
     }),
 ]);
 const entityDetailsInputSchema = z.object({
-    connectionId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),
+    connectionId: z.string().regex(/^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/),
     targets: z.array(targetSchema).min(1).max(50),
 }).strict();
 function allowedConnectionNames(context) {

package/dist/context/ingest/tools/warehouse-verification/sql-execution.tool.js

@@ -3,7 +3,7 @@ import { assertReadOnlySql, limitSqlForExecution } from '../../../../context/con
 import { sqlAnalysisDialectForDriver } from '../../../../context/sql-analysis/dialect.js';
 import { BaseTool } from '../../../../context/tools/base-tool.js';
 const sqlExecutionInputSchema = z.object({
-    connectionId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),
+    connectionId: z.string().regex(/^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/),
     sql: z.string().min(1),
     rowLimit: z.number().int().positive().max(1000).optional().default(100),
 }).strict();

package/dist/context/ingest/types.d.ts

@@ -6,6 +6,7 @@ import type { KtxTableRefKey } from '../scan/table-ref.js';
 import type { MemoryFlowEventSink } from './memory-flow/types.js';
 import type { StageIndex } from './stages/stage-index.types.js';
 import type { WorkUnitOutcome } from './stages/stage-3-work-units.js';
+import type { FinalGateDroppedSource, FinalGatePrunedReference } from './final-gate-prune.js';
 export type IngestTrigger = 'upload' | 'scheduled_pull' | 'manual_resync' | 'manual_override';
 export interface DiffSet {
     added: string[];
@@ -190,6 +191,8 @@ export interface IngestBundleResult {
     failedWorkUnits: string[];
     artifactsWritten: number;
     commitSha: string | null;
+    finalGatePrunedReferences?: FinalGatePrunedReference[];
+    finalGateDroppedSources?: FinalGateDroppedSource[];
 }
 export interface IngestJobPhase {
     updateProgress(progress: number, message?: string): Promise<void>;

package/dist/context/ingest/wiki-body-refs.d.ts

@@ -5,14 +5,17 @@ export type WikiBodyRef = {
     connectionId: string | null;
     sourceName: string;
     entityName: string;
+    rawToken: string;
 } | {
     kind: 'sl_source';
     connectionId: string | null;
     sourceName: string;
+    rawToken: string;
 } | {
     kind: 'table';
     connectionId: string | null;
     tableRef: string;
+    rawToken: string;
 };
 export interface WikiBodyRefValidationInput {
     pageKey: string;
@@ -21,6 +24,31 @@ export interface WikiBodyRefValidationInput {
     loadSources(connectionId: string): Promise<SemanticLayerSource[]>;
     tableExists(connectionId: string, tableRef: string): Promise<boolean>;
 }
+export type WikiBodyRefIssue = {
+    kind: 'missing_wiki_body_sl_entity';
+    pageKey: string;
+    rawToken: string;
+    connectionId?: string;
+    sourceName: string;
+    entityName: string;
+    message: string;
+} | {
+    kind: 'missing_wiki_body_sl_source';
+    pageKey: string;
+    rawToken: string;
+    connectionId?: string;
+    sourceName: string;
+    message: string;
+} | {
+    kind: 'missing_wiki_body_table';
+    pageKey: string;
+    rawToken: string;
+    connectionId?: string;
+    tableRef: string;
+    message: string;
+};
 /** @internal */
 export declare function parseWikiBodyRefs(body: string): WikiBodyRef[];
+export declare function findInvalidWikiBodyRefIssues(input: WikiBodyRefValidationInput): Promise<WikiBodyRefIssue[]>;
+/** @internal */
 export declare function findInvalidWikiBodyRefs(input: WikiBodyRefValidationInput): Promise<string[]>;

package/dist/context/ingest/wiki-body-refs.js

@@ -36,14 +36,14 @@ export function parseWikiBodyRefs(body) {
             if (scoped.body.startsWith('source:')) {
                 const sourceName = scoped.body.slice('source:'.length).trim();
                 if (sourceName) {
-                    refs.push({ kind: 'sl_source', connectionId: scoped.connectionId, sourceName });
+                    refs.push({ kind: 'sl_source', connectionId: scoped.connectionId, sourceName, rawToken: token });
                 }
                 continue;
             }
             if (scoped.body.startsWith('table:')) {
                 const tableRef = scoped.body.slice('table:'.length).trim();
                 if (tableRef) {
-                    refs.push({ kind: 'table', connectionId: scoped.connectionId, tableRef });
+                    refs.push({ kind: 'table', connectionId: scoped.connectionId, tableRef, rawToken: token });
                 }
                 continue;
             }
@@ -54,6 +54,7 @@ export function parseWikiBodyRefs(body) {
                     connectionId: scoped.connectionId,
                     sourceName: parts[0],
                     entityName: parts[1],
+                    rawToken: token,
                 });
             }
         }
@@ -67,8 +68,8 @@ function entityNames(source) {
         ...(source.segments ?? []).map((segment) => segment.name),
     ]);
 }
-export async function findInvalidWikiBodyRefs(input) {
-    const errors = [];
+export async function findInvalidWikiBodyRefIssues(input) {
+    const issues = [];
     const sourceCache = new Map();
     const loadSources = async (connectionId) => {
         const cached = sourceCache.get(connectionId);
@@ -93,20 +94,48 @@ export async function findInvalidWikiBodyRefs(input) {
         if (ref.kind === 'table') {
             const found = await Promise.all(connectionIds.map((connectionId) => input.tableExists(connectionId, ref.tableRef)));
             if (!found.some(Boolean)) {
-                errors.push(`${input.pageKey}: unknown raw table ${ref.connectionId ? `${ref.connectionId}/` : ''}${ref.tableRef}`);
+                const target = `${ref.connectionId ? `${ref.connectionId}/` : ''}${ref.tableRef}`;
+                issues.push({
+                    kind: 'missing_wiki_body_table',
+                    pageKey: input.pageKey,
+                    rawToken: ref.rawToken,
+                    ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+                    tableRef: ref.tableRef,
+                    message: `${input.pageKey}: unknown raw table ${target}`,
+                });
             }
             continue;
         }
         const found = await findSource(connectionIds, ref.sourceName);
         if (!found) {
             if (ref.kind === 'sl_source') {
-                errors.push(`${input.pageKey}: unknown semantic-layer source ${ref.connectionId ? `${ref.connectionId}/` : ''}${ref.sourceName}`);
+                const target = `${ref.connectionId ? `${ref.connectionId}/` : ''}${ref.sourceName}`;
+                issues.push({
+                    kind: 'missing_wiki_body_sl_source',
+                    pageKey: input.pageKey,
+                    rawToken: ref.rawToken,
+                    ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+                    sourceName: ref.sourceName,
+                    message: `${input.pageKey}: unknown semantic-layer source ${target}`,
+                });
             }
             continue;
         }
         if (ref.kind === 'sl_entity' && !entityNames(found.source).has(ref.entityName)) {
-            errors.push(`${input.pageKey}: unknown semantic-layer entity ${ref.sourceName}.${ref.entityName}`);
+            issues.push({
+                kind: 'missing_wiki_body_sl_entity',
+                pageKey: input.pageKey,
+                rawToken: ref.rawToken,
+                ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+                sourceName: ref.sourceName,
+                entityName: ref.entityName,
+                message: `${input.pageKey}: unknown semantic-layer entity ${ref.sourceName}.${ref.entityName}`,
+            });
         }
     }
-    return errors;
+    return issues;
+}
+/** @internal */
+export async function findInvalidWikiBodyRefs(input) {
+    return (await findInvalidWikiBodyRefIssues(input)).map((issue) => issue.message);
 }

package/dist/context/ingest/wiki-sl-ref-repair.d.ts

@@ -16,4 +16,5 @@ export declare function repairWikiSlRefs(input: {
     semanticLayerService: SemanticLayerService;
     configService: KtxFileStorePort;
     connectionIds: string[];
+    deferGlobalPageKeys?: string[];
 }): Promise<WikiSlRefRepairResult>;

package/dist/context/ingest/wiki-sl-ref-repair.js

@@ -57,11 +57,15 @@ export async function repairWikiSlRefs(input) {
     }
     const listed = await listFiles('wiki', true);
     const repairs = [];
+    const deferredGlobalPageKeys = new Set(input.deferGlobalPageKeys ?? []);
     for (const file of listed.files.sort()) {
         const parsedPath = parseKnowledgeFilePath(file);
         if (!parsedPath) {
             continue;
         }
+        if (parsedPath.scope === 'GLOBAL' && deferredGlobalPageKeys.has(parsedPath.pageKey)) {
+            continue;
+        }
         const page = await input.wikiService.readPage(parsedPath.scope, parsedPath.scopeId, parsedPath.pageKey);
         const refs = uniqueStringArray(page?.frontmatter.sl_refs);
         if (!page || refs.length === 0) {

package/dist/context/ingest/work-unit-cache.d.ts

@@ -0,0 +1,67 @@
+import type { KtxModelRole } from '../../llm/types.js';
+import type { GitService } from '../core/git.service.js';
+import type { MemoryAction } from '../memory/types.js';
+import type { TouchedSlSource } from '../tools/touched-sl-sources.js';
+import type { IngestTraceWriter } from './ingest-trace.js';
+import type { IngestSessionWorktreePort } from './ports.js';
+import type { WorkUnit } from './types.js';
+export declare const INGEST_WORK_UNIT_CACHE_NAMESPACE = "ingest:work-unit";
+export interface IngestWorkUnitCachedArtifactFile {
+    path: string;
+    beforeBase64: string | null;
+    afterBase64: string | null;
+}
+export interface IngestWorkUnitCachePayload {
+    schemaVersion: 2;
+    unitKey: string;
+    patchTouchedPaths: string[];
+    artifactFiles: IngestWorkUnitCachedArtifactFile[];
+    actions: MemoryAction[];
+    touchedSlSources: TouchedSlSource[];
+    slDisallowed?: boolean;
+    slDisallowedReason?: 'lookml_connection_mismatch';
+}
+export interface ComputeIngestWorkUnitInputHashInput {
+    stagedDir: string;
+    connectionId: string;
+    sourceKey: string;
+    unit: WorkUnit;
+    cliVersion: string;
+    promptFingerprint: string;
+    modelRole: KtxModelRole;
+}
+export declare function computeIngestWorkUnitInputHash(input: ComputeIngestWorkUnitInputHashInput): Promise<string>;
+/** @internal */
+export declare function isPruneShapedCachedReplayBase(path: string, currentContent: string, outputContent: string): boolean;
+export declare function captureIngestWorkUnitCachedArtifactFiles(input: {
+    git: GitService;
+    workdir: string;
+    baseSha: string;
+    patchTouchedPaths: string[];
+}): Promise<IngestWorkUnitCachedArtifactFile[]>;
+export declare function materializeCachedWorkUnitReplayPatch(input: {
+    sessionWorktreeService: IngestSessionWorktreePort;
+    baseSha: string;
+    jobId: string;
+    unitKey: string;
+    patchPath: string;
+    artifactFiles: IngestWorkUnitCachedArtifactFile[];
+    author: {
+        name: string;
+        email: string;
+    };
+    trace: IngestTraceWriter;
+}): Promise<'materialized' | 'unsafe_drift'>;
+export declare function ingestWorkUnitCacheScopeKey(input: {
+    connectionId: string;
+    sourceKey: string;
+}): string;
+export declare function computeIngestWorkUnitPromptFingerprint(input: {
+    cliVersion: string;
+    baseFraming: string;
+    skillsPrompt: string;
+    canonicalPins: unknown[];
+    sourceKey: string;
+    connectionId: string;
+    skillNames: string[];
+}): string;

package/dist/context/ingest/work-unit-cache.js

@@ -0,0 +1,230 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import YAML from 'yaml';
+import { stableContentHash } from '../cache/content-result-cache.js';
+export const INGEST_WORK_UNIT_CACHE_NAMESPACE = 'ingest:work-unit';
+async function fileDigest(stagedDir, path) {
+    try {
+        const bytes = await readFile(join(stagedDir, path));
+        return { path, status: 'present', hash: stableContentHash(bytes.toString('base64')) };
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return { path, status: 'missing', hash: null };
+        }
+        throw error;
+    }
+}
+export async function computeIngestWorkUnitInputHash(input) {
+    const rawFiles = [...input.unit.rawFiles].sort();
+    const dependencyPaths = [...input.unit.dependencyPaths].sort();
+    const [raw, dependencies] = await Promise.all([
+        Promise.all(rawFiles.map((path) => fileDigest(input.stagedDir, path))),
+        Promise.all(dependencyPaths.map((path) => fileDigest(input.stagedDir, path))),
+    ]);
+    return stableContentHash({
+        schemaVersion: 2,
+        connectionId: input.connectionId,
+        sourceKey: input.sourceKey,
+        unitKey: input.unit.unitKey,
+        rawFiles: raw,
+        dependencyPaths: dependencies,
+        slDisallowed: input.unit.slDisallowed === true,
+        slDisallowedReason: input.unit.slDisallowedReason ?? null,
+        cliVersion: input.cliVersion,
+        promptFingerprint: input.promptFingerprint,
+        modelRole: input.modelRole,
+    });
+}
+async function readFileBase64(workdir, path) {
+    try {
+        return (await readFile(join(workdir, path))).toString('base64');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+async function readGitFileBase64(git, path, commitSha) {
+    try {
+        return Buffer.from(await git.getFileAtCommit(path, commitSha), 'utf-8').toString('base64');
+    }
+    catch {
+        return null;
+    }
+}
+function decodeBase64(value) {
+    return value === null ? null : Buffer.from(value, 'base64').toString('utf-8');
+}
+function parseYamlObject(content) {
+    const parsed = YAML.parse(content);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+}
+function isSubsequenceOfDeepValues(current, output) {
+    let outputIndex = 0;
+    for (const item of current) {
+        while (outputIndex < output.length && !isDeepStrictEqual(item, output[outputIndex])) {
+            outputIndex += 1;
+        }
+        if (outputIndex >= output.length) {
+            return false;
+        }
+        outputIndex += 1;
+    }
+    return true;
+}
+function isSemanticLayerPruneShape(current, output) {
+    const currentYaml = parseYamlObject(current);
+    const outputYaml = parseYamlObject(output);
+    if (!currentYaml || !outputYaml) {
+        return false;
+    }
+    const currentJoins = Array.isArray(currentYaml.joins) ? currentYaml.joins : [];
+    const outputJoins = Array.isArray(outputYaml.joins) ? outputYaml.joins : [];
+    if (currentJoins.length >= outputJoins.length) {
+        return false;
+    }
+    if (!isSubsequenceOfDeepValues(currentJoins, outputJoins)) {
+        return false;
+    }
+    const normalizedOutput = { ...outputYaml, joins: currentJoins };
+    return isDeepStrictEqual(currentYaml, normalizedOutput);
+}
+function parseWikiPage(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) {
+        return null;
+    }
+    const frontmatter = YAML.parse(match[1] ?? '');
+    return { frontmatter, content: (match[2] ?? '').trim() };
+}
+function withoutRemovedWikiTokens(output, current) {
+    let projected = output;
+    for (const match of output.matchAll(/\[\[\s*([^|\]\n]+)(?:\|[^\]\n]+)?\s*\]\]/g)) {
+        const token = match[0] ?? '';
+        if (token && !current.includes(token)) {
+            projected = projected.replaceAll(token, '').replace(/[ \t]+([.,;:!?])/g, '$1');
+        }
+    }
+    for (const match of output.matchAll(/`([^`\n]+)`/g)) {
+        const token = match[0] ?? '';
+        if (token && !current.includes(token)) {
+            projected = projected.replaceAll(token, '').replace(/[ \t]+([.,;:!?])/g, '$1');
+        }
+    }
+    projected = projected.replace(/,\s*,/g, ',').replace(/[ \t]+([.,;:!?])/g, '$1');
+    return projected.trim();
+}
+function isWikiPruneShape(current, output) {
+    const currentPage = parseWikiPage(current);
+    const outputPage = parseWikiPage(output);
+    if (!currentPage || !outputPage) {
+        return false;
+    }
+    const currentRefs = Array.isArray(currentPage.frontmatter.refs) ? currentPage.frontmatter.refs : [];
+    const outputRefs = Array.isArray(outputPage.frontmatter.refs) ? outputPage.frontmatter.refs : [];
+    const currentSlRefs = Array.isArray(currentPage.frontmatter.sl_refs) ? currentPage.frontmatter.sl_refs : [];
+    const outputSlRefs = Array.isArray(outputPage.frontmatter.sl_refs) ? outputPage.frontmatter.sl_refs : [];
+    if (currentRefs.length > outputRefs.length || currentSlRefs.length > outputSlRefs.length) {
+        return false;
+    }
+    if (!isSubsequenceOfDeepValues(currentRefs, outputRefs) || !isSubsequenceOfDeepValues(currentSlRefs, outputSlRefs)) {
+        return false;
+    }
+    const normalizedOutputFrontmatter = {
+        ...outputPage.frontmatter,
+        refs: currentRefs,
+        sl_refs: currentSlRefs,
+    };
+    if (!isDeepStrictEqual(currentPage.frontmatter, normalizedOutputFrontmatter)) {
+        return false;
+    }
+    return withoutRemovedWikiTokens(outputPage.content, currentPage.content) === currentPage.content.trim();
+}
+/** @internal */
+export function isPruneShapedCachedReplayBase(path, currentContent, outputContent) {
+    if (path.startsWith('semantic-layer/') && path.endsWith('.yaml')) {
+        return isSemanticLayerPruneShape(currentContent, outputContent);
+    }
+    if (path.startsWith('wiki/') && path.endsWith('.md')) {
+        return isWikiPruneShape(currentContent, outputContent);
+    }
+    return false;
+}
+export async function captureIngestWorkUnitCachedArtifactFiles(input) {
+    const paths = [...new Set(input.patchTouchedPaths)].sort();
+    return Promise.all(paths.map(async (path) => ({
+        path,
+        beforeBase64: await readGitFileBase64(input.git, path, input.baseSha),
+        afterBase64: await readFileBase64(input.workdir, path),
+    })));
+}
+async function writeCachedFile(workdir, file) {
+    const target = join(workdir, file.path);
+    if (file.afterBase64 === null) {
+        await rm(target, { force: true });
+        return;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, Buffer.from(file.afterBase64, 'base64'));
+}
+function cacheFileCanReplayFromCurrentBase(file, currentBase64) {
+    if (currentBase64 === file.beforeBase64 || currentBase64 === file.afterBase64) {
+        return true;
+    }
+    const current = decodeBase64(currentBase64);
+    const output = decodeBase64(file.afterBase64);
+    if (current === null || output === null) {
+        return false;
+    }
+    return isPruneShapedCachedReplayBase(file.path, current, output);
+}
+export async function materializeCachedWorkUnitReplayPatch(input) {
+    const replay = await input.sessionWorktreeService.create(`${input.jobId}-${input.unitKey}-cache-replay`, input.baseSha);
+    let cleanup = 'crash';
+    try {
+        for (const file of input.artifactFiles) {
+            const currentBase64 = await readFileBase64(replay.workdir, file.path);
+            if (!cacheFileCanReplayFromCurrentBase(file, currentBase64)) {
+                cleanup = 'success';
+                return 'unsafe_drift';
+            }
+        }
+        for (const file of input.artifactFiles) {
+            await writeCachedFile(replay.workdir, file);
+        }
+        const changedPaths = await replay.git.changedPaths();
+        if (changedPaths.length > 0) {
+            await replay.git.commitFiles(changedPaths, `ingest: materialize cached WorkUnit ${input.unitKey}`, input.author.name, input.author.email);
+        }
+        await replay.git.writeBinaryNoRenamePatch(input.baseSha, 'HEAD', input.patchPath);
+        await input.trace.event('debug', 'work_unit', 'work_unit_cache_patch_materialized', {
+            unitKey: input.unitKey,
+            patchPath: input.patchPath,
+            touchedPaths: changedPaths,
+        });
+        cleanup = 'success';
+        return 'materialized';
+    }
+    finally {
+        await input.sessionWorktreeService.cleanup(replay, cleanup);
+    }
+}
+export function ingestWorkUnitCacheScopeKey(input) {
+    return `${input.connectionId}:${input.sourceKey}`;
+}
+export function computeIngestWorkUnitPromptFingerprint(input) {
+    return stableContentHash({
+        schemaVersion: 1,
+        cliVersion: input.cliVersion,
+        baseFraming: input.baseFraming,
+        skillsPrompt: input.skillsPrompt,
+        canonicalPins: input.canonicalPins,
+        sourceKey: input.sourceKey,
+        connectionId: input.connectionId,
+        skillNames: [...input.skillNames].sort(),
+    });
+}

package/dist/context/llm/ai-sdk-runtime.d.ts

@@ -19,6 +19,7 @@ export declare class AiSdkKtxLlmRuntime implements KtxLlmRuntimePort {
     private readonly deps;
     private readonly logger;
     constructor(deps: AiSdkKtxLlmRuntimeDeps);
+    subprocessForkSpec(): null;
     private generateTextWithRateLimitRetry;
     generateText(input: KtxGenerateTextInput): Promise<string>;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;

package/dist/context/llm/ai-sdk-runtime.js

@@ -126,6 +126,11 @@ export class AiSdkKtxLlmRuntime {
         this.deps = deps;
         this.logger = deps.logger ?? noopLogger;
     }
+    // HTTP backend: abortSignal cancels the underlying fetch natively, so there is
+    // no SDK-owned child to tree-kill.
+    subprocessForkSpec() {
+        return null;
+    }
     async generateTextWithRateLimitRetry(provider, abortSignal, run) {
         // maxRetryAttempts() returns 1 when no governor is present or pacing is
         // disabled, so a 429 throws immediately instead of hammering the provider

package/dist/context/llm/claude-code-runtime.d.ts

@@ -1,7 +1,7 @@
 import { query as defaultQuery, type SDKMessage, type SDKResultMessage } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import type { RateLimitGovernor } from './rate-limit-governor.js';
-import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, RunLoopParams, RunLoopResult, RunLoopStopReason } from './runtime-port.js';
+import type { KtxGenerateObjectInput, KtxGenerateStructuredJsonInput, KtxGenerateTextInput, KtxLlmRuntimePort, RunLoopParams, RunLoopResult, RunLoopStopReason, SubprocessRuntimeForkSpec } from './runtime-port.js';
 type QueryResult = AsyncIterable<SDKMessage> & {
     interrupt?: () => void | Promise<void>;
 };
@@ -22,7 +22,10 @@ export declare class ClaudeCodeKtxLlmRuntime implements KtxLlmRuntimePort {
     private readonly runQuery;
     constructor(deps: ClaudeCodeKtxLlmRuntimeDeps);
     generateText(input: KtxGenerateTextInput): Promise<string>;
+    private runStructuredQuery;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;
+    generateStructuredJson(input: KtxGenerateStructuredJsonInput): Promise<unknown>;
+    subprocessForkSpec(): SubprocessRuntimeForkSpec;
     runAgentLoop(params: RunLoopParams): Promise<RunLoopResult>;
 }
 export declare function runClaudeCodeAuthProbe(input: {

package/dist/context/llm/claude-code-runtime.js

@@ -298,7 +298,9 @@ export class ClaudeCodeKtxLlmRuntime {
         }
         return result.result;
     }
-    async generateObject(input) {
+    // Structured generation has no tools, so generateObject and
+    // generateStructuredJson (the kill-boundary child path) share this one query.
+    async runStructuredQuery(input) {
         const options = {
             ...baseOptions({
                 projectDir: this.deps.projectDir,
@@ -310,19 +312,27 @@ export class ClaudeCodeKtxLlmRuntime {
                 // 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', schema: jsonSchema(input.schema) },
+            outputFormat: { type: 'json_schema', schema: input.jsonSchema },
         };
-        const startedAt = Date.now();
-        const result = await collectResultWithRateLimitRetry({
+        return collectResultWithRateLimitRetry({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
             options,
-            allowedToolIds: new Set([...mcpToolIds(input.tools ?? {}), STRUCTURED_OUTPUT_TOOL_NAME]),
-            expectedMcpServerNames: expectedMcpServerNames(input.tools),
+            allowedToolIds: new Set([STRUCTURED_OUTPUT_TOOL_NAME]),
+            expectedMcpServerNames: new Set(),
             rateLimitGovernor: this.deps.rateLimitGovernor,
-            abortSignal: input.abortSignal,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
+        });
+    }
+    async generateObject(input) {
+        const startedAt = Date.now();
+        const result = await this.runStructuredQuery({
+            role: input.role,
+            prompt: input.prompt,
+            ...(input.system !== undefined ? { system: input.system } : {}),
+            jsonSchema: jsonSchema(input.schema),
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
         });
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
@@ -334,6 +344,26 @@ export class ClaudeCodeKtxLlmRuntime {
         }
         return input.schema.parse(result.structured_output);
     }
+    async generateStructuredJson(input) {
+        const result = await this.runStructuredQuery({
+            role: input.role,
+            prompt: input.prompt,
+            ...(input.system !== undefined ? { system: input.system } : {}),
+            jsonSchema: input.jsonSchema,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
+        });
+        const error = resultError(result);
+        if (error) {
+            throw error;
+        }
+        if (result.subtype !== 'success') {
+            throw new Error(`Claude Code query failed (${result.subtype})`);
+        }
+        return result.structured_output;
+    }
+    subprocessForkSpec() {
+        return { backend: 'claude-code', projectDir: this.deps.projectDir, modelSlots: this.deps.modelSlots };
+    }
     async runAgentLoop(params) {
         const startedAt = Date.now();
         try {