stitchkit 0.68.10 → 0.69.0

package/README.md

@@ -103,6 +103,15 @@ cursor but no execution, persistence or sink graph.
 Durable embedded storage is isolated behind
 `stitchkit/agent-runtime/sqlite/bun` and `stitchkit/agent-runtime/sqlite/node`;
 neither runtime-specific built-in leaks into the neutral or browser entrypoint.
+Externally supervised sessions can compose the same runtime through
+`stitchkit/agent-runtime/harness`; optional explicit-root lazy resources, signed approval
+continuations and reconnectable control compose there. Bounded direct file, search, guarded patch,
+shell and opaque-artifact tools live in the peer-free
+`stitchkit/agent-runtime/coding-tools` leaf. Neither surface owns process placement,
+restart, credentials, model catalogs or OS isolation.
+The separately installed `@stitchkit/tui` package adds a maintained Bun/OpenTUI host over those
+headless contracts; its `@stitchkit/tui/core` entrypoint exposes renderer-neutral terminal state
+without React, OpenTUI or agent-runtime imports. Neither enters the core dependency graph.
 
 ## Managed application kernel
 
@@ -339,7 +348,7 @@ import { parseSSE } from 'stitchkit'           // client: Response → AsyncGene
 | **MCP Tools** | `createMcpHandler()` / `mountMcp()` — MCP tools from contracts |
 | **Agent Tools** | `mountAgent()` — Vercel AI SDK tools from contracts |
 | **Agent Runtime** | `createAgentRuntime()` — optional durable history, stream loop, coordination and fencing |
-| **Application Kernel** | `createApplication()` — optional process-local resources, readiness, schedules and bounded shutdown |
+| **Application Kernel** | `createApplication()` plus optional bounded local diagnostics — process-local resources, readiness, schedules and bounded shutdown |
 | **Typed Client** | `createClient()` / `createClients()` — typed fetch from contracts |
 | **Cursor Pagination** | `createCursorQuery()` — `react-query-kit` infinite query from a contract method |
 | **WebSocket** | `createSocketIOClient()` / `createSocketIOServer()` — typed Socket.IO wrappers |
@@ -426,6 +435,9 @@ peer — an install pulls in only what the project actually uses.
 | `@modelcontextprotocol/client` | development dependency, optional | Only consumers that run MCP client integration tests or build an MCP host. |
 | `@modelcontextprotocol/ext-apps` | peer, optional | Only MCP Apps (`ui://` resources and UI metadata). |
 | `ai` | peer, optional | `stitchkit/tools` agent tools and the optional server-only `stitchkit/agent-runtime`. |
+| Headless harness | optional surface | `stitchkit/agent-runtime/harness`; uses the same optional `ai` peer and canonical runtime. |
+| Agent coding tools | optional surface | `stitchkit/agent-runtime/coding-tools`; peer-free, host-authorized direct file and shell tools. |
+| `@stitchkit/tui` | separate optional package | Renderer-neutral `./core` state plus a Bun/OpenTUI terminal controller, commands, model/session pickers and authenticated local attachment over a caller-composed harness. |
 | `@openrouter/ai-sdk-provider` | peer, optional | Only `stitchkit/agent-runtime/openrouter`; neutral runtime imports do not resolve it. |
 | SQLite | runtime built-in, optional | `bun:sqlite` through `stitchkit/agent-runtime/sqlite/bun`, or `node:sqlite` on Node ≥ 22.5 through the Node leaf. |
 | `grammy` | peer, optional | Only `stitchkit/application/grammy`; the neutral application kernel does not resolve it. |
@@ -455,6 +467,23 @@ external infrastructure configured through `DATABASE_URL`.
 The template owns a committed Bun lockfile and an explicit Stitchkit catalog
 range, so framework and scaffolder releases advance independently.
 
+For a minimal terminal coding-agent host, choose the second explicit profile:
+
+```bash
+bun create stitchkit my-agent --template agent
+cd my-agent
+cp .env.example .env
+# Fill OPENROUTER_API_KEY, then choose a live model in the terminal.
+bun run dev
+```
+
+Its editable `stitchkit.agent.ts` composes `@stitchkit/tui`, OpenRouter, durable SQLite history,
+lazy skills and direct approval-gated coding tools over the same headless Agent harness. `/model`
+searches the full tool-capable catalog and shows weekly popularity independently from sourced
+benchmark observations. `/status` exposes the local session ID so another process can `send` or
+`interrupt` through the terminal's existing controller. The renderer and provider dependencies do
+not enter Stitchkit core or the default application. → [ADR 0133](./docs/decisions/0133-agent-tui-is-an-optional-package-over-one-controller.md)
+
 ## Documentation — two roads
 
 This README is the quick start. Where you go next depends on what you're doing:

package/dist/agent-runtime/coding-tool-contract.d.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod';
+export declare const AgentCodingToolLimitsSchema: z.ZodObject<{
+    maxPathBytes: z.ZodInt;
+    maxReadBytes: z.ZodInt;
+    maxWriteBytes: z.ZodInt;
+    maxShellArguments: z.ZodInt;
+    maxShellArgumentBytes: z.ZodInt;
+    maxShellOutputBytes: z.ZodInt;
+    maxArtifactBytes: z.ZodInt;
+    maxSearchResults: z.ZodInt;
+    maxSearchFiles: z.ZodInt;
+    maxSearchDepth: z.ZodInt;
+    shellTimeoutMs: z.ZodInt;
+}, z.core.$strict>;
+export declare const AgentCodingToolAuthorizationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"write">;
+    path: z.ZodString;
+    bytes: z.ZodInt;
+    overwrite: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"search">;
+    query: z.ZodString;
+    mode: z.ZodEnum<{
+        content: "content";
+        path: "path";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"patch">;
+    path: z.ZodString;
+    baseSha256: z.ZodString;
+    resultSha256: z.ZodString;
+    resultBytes: z.ZodInt;
+    replacements: z.ZodInt;
+    dryRun: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"artifact-read">;
+    reference: z.ZodString;
+    offset: z.ZodInt;
+    maxBytes: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"shell">;
+    executable: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+}, z.core.$strict>], "operation">;
+export type AgentCodingToolLimits = z.infer<typeof AgentCodingToolLimitsSchema>;
+export type AgentCodingToolAuthorization = z.infer<typeof AgentCodingToolAuthorizationSchema>;
+export interface AgentCodingToolConfig {
+    root: string;
+    authorize(input: AgentCodingToolAuthorization): boolean | Promise<boolean>;
+    executables?: Readonly<Record<string, string>>;
+    environment?: Readonly<Record<string, string>>;
+    artifacts?: AgentCodingArtifactStore;
+    search?: {
+        /** Directory basenames omitted from workspace search at every depth. */
+        excludeDirectories?: readonly string[];
+    };
+    limits?: Partial<AgentCodingToolLimits>;
+}
+export interface AgentCodingArtifactStore {
+    write(input: {
+        mediaType: string;
+        data: Uint8Array;
+    }): {
+        reference: string;
+    } | Promise<{
+        reference: string;
+    }>;
+    read(input: {
+        reference: string;
+        offset: number;
+        maxBytes: number;
+    }): {
+        data: Uint8Array;
+        totalBytes?: number;
+    } | Promise<{
+        data: Uint8Array;
+        totalBytes?: number;
+    }>;
+}
+export interface AgentCodingToolDefinition {
+    name: string;
+    description: string;
+    identity: {
+        serviceName: string;
+        action: string;
+        method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    };
+    input: z.ZodObject;
+    output: z.ZodType;
+    transports?: readonly ('MCP' | 'AGENT' | 'CLI')[];
+    handler(context: {
+        params: undefined;
+        input: unknown;
+        signal?: AbortSignal;
+        [key: string]: unknown;
+    }): unknown | Promise<unknown>;
+}
+export declare const FileReadInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    offset: z.ZodDefault<z.ZodInt>;
+    maxBytes: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+export declare const FileReadOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    text: z.ZodString;
+    bytes: z.ZodInt;
+    sha256: z.ZodString;
+    truncated: z.ZodBoolean;
+    nextOffset: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+export declare const FileWriteInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+    overwrite: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const FileWriteOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    bytes: z.ZodInt;
+}, z.core.$strict>;
+export declare function createShellInputSchema(executableNames: readonly string[]): z.ZodObject<{
+    executable: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export declare const ShellInputSchema: z.ZodObject<{
+    executable: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export declare const ShellOutputSchema: z.ZodObject<{
+    executable: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodInt>;
+    signal: z.ZodNullable<z.ZodString>;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    outcome: z.ZodEnum<{
+        cancelled: "cancelled";
+        exited: "exited";
+        "output-limit": "output-limit";
+        timeout: "timeout";
+    }>;
+    artifact: z.ZodOptional<z.ZodObject<{
+        reference: z.ZodString;
+        bytes: z.ZodInt;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare function resolveCodingToolLimits(input: Partial<AgentCodingToolLimits> | undefined): AgentCodingToolLimits;
+//# sourceMappingURL=coding-tool-contract.d.ts.map

package/dist/agent-runtime/coding-tool-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-tool-contract.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-contract.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime/coding-tool-files.d.ts

@@ -0,0 +1,3 @@
+import { type AgentCodingToolConfig, type AgentCodingToolDefinition, type AgentCodingToolLimits } from './coding-tool-contract.js';
+export declare function createFileCodingTools(config: AgentCodingToolConfig, limits: AgentCodingToolLimits): readonly AgentCodingToolDefinition[];
+//# sourceMappingURL=coding-tool-files.d.ts.map

package/dist/agent-runtime/coding-tool-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-tool-files.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-files.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAK3B,MAAM,wBAAwB,CAAC;AAwBhC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,SAAS,yBAAyB,EAAE,CAyEtC"}

package/dist/agent-runtime/coding-tool-paths.d.ts

@@ -0,0 +1,19 @@
+import { type AgentCodingToolAuthorization, type AgentCodingToolConfig } from './coding-tool-contract.js';
+export declare function existingCodingPath(root: string, requested: string, maxPathBytes: number): Promise<{
+    absolute: string;
+    relative: string;
+}>;
+export declare function writableCodingPath(root: string, requested: string, maxPathBytes: number): Promise<{
+    absolute: string;
+    relative: string;
+}>;
+export declare function editableCodingPath(root: string, requested: string, maxPathBytes: number): Promise<{
+    absolute: string;
+    relative: string;
+}>;
+export declare function authorizeCodingTool(config: AgentCodingToolConfig, request: AgentCodingToolAuthorization): Promise<void>;
+export declare function atomicCodingReplace(target: string, content: string, mode?: number): Promise<void>;
+/** Serialize framework-owned compare-and-replace transactions for one canonical target. */
+export declare function withCodingPathLock<T>(target: string, work: () => Promise<T>): Promise<T>;
+export declare function textOccurrences(source: string, search: string): number;
+//# sourceMappingURL=coding-tool-paths.d.ts.map

package/dist/agent-runtime/coding-tool-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-tool-paths.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-paths.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,4BAA4B,EAEjC,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAoBhC,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAKrB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAarB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAQrB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAYf;AAID,2FAA2F;AAC3F,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUtE"}

package/dist/agent-runtime/coding-tool-search-patch.d.ts

@@ -0,0 +1,3 @@
+import type { AgentCodingToolConfig, AgentCodingToolDefinition, AgentCodingToolLimits } from './coding-tool-contract.js';
+export declare function createSearchAndPatchCodingTools(config: AgentCodingToolConfig, limits: AgentCodingToolLimits): readonly AgentCodingToolDefinition[];
+//# sourceMappingURL=coding-tool-search-patch.d.ts.map

package/dist/agent-runtime/coding-tool-search-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-tool-search-patch.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-search-patch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AA2DhC,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,SAAS,yBAAyB,EAAE,CAmHtC"}

package/dist/agent-runtime/coding-tool-shell.d.ts

@@ -0,0 +1,3 @@
+import { type AgentCodingToolConfig, type AgentCodingToolDefinition, type AgentCodingToolLimits } from './coding-tool-contract.js';
+export declare function createShellCodingTool(config: AgentCodingToolConfig, limits: AgentCodingToolLimits): AgentCodingToolDefinition;
+//# sourceMappingURL=coding-tool-shell.d.ts.map

package/dist/agent-runtime/coding-tool-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-tool-shell.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-shell.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAG3B,MAAM,wBAAwB,CAAC;AA+GhC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,yBAAyB,CAiD3B"}

package/dist/agent-runtime/coding-tools.d.ts

@@ -0,0 +1,17 @@
+import { type AgentCodingToolConfig, type AgentCodingToolDefinition } from './coding-tool-contract.js';
+export * from './coding-tool-contract.js';
+export declare const AGENT_CODING_TOOL_NAMES: {
+    applyPatch: string;
+    readFile: string;
+    readOutput: string;
+    runCommand: string;
+    searchFiles: string;
+    writeFile: string;
+};
+/**
+ * Direct Agent runtime-tool definitions for a host-authorized coding profile.
+ * The root is a path boundary, not an OS sandbox; the host must still isolate
+ * the process when it needs protection from arbitrary executable behavior.
+ */
+export declare function createAgentCodingTools(config: AgentCodingToolConfig): readonly AgentCodingToolDefinition[];
+//# sourceMappingURL=coding-tools.d.ts.map

package/dist/agent-runtime/coding-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-tools.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tools.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAE/B,MAAM,wBAAwB,CAAC;AAMhC,cAAc,wBAAwB,CAAC;AAEvC,eAAO,MAAM,uBAAuB;;;;;;;CAOQ,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,qBAAqB,GAC5B,SAAS,yBAAyB,EAAE,CA6EtC"}

package/dist/agent-runtime/compaction.d.ts

@@ -1,6 +1,7 @@
 import type { ZodType, z } from 'zod';
 import type { AgentMessage, AgentSnapshot, AgentUsage } from './schemas.js';
 import type { AgentRuntimeStore } from './store.js';
+import { type AgentHistoryEvidencePolicy } from './terminal-status.js';
 export interface AgentCompactionContext<SUMMARY> {
     conversationId: string;
     snapshot: AgentSnapshot;
@@ -11,6 +12,7 @@ export interface AgentCompactionContext<SUMMARY> {
 export interface StructuredCompactionConfig<SUMMARY_SCHEMA extends ZodType> {
     schema: SUMMARY_SCHEMA;
     keepRecentTurns: number;
+    evidencePolicy?: AgentHistoryEvidencePolicy;
     /** Total summarize/CAS attempts. A conflict always recomputes from a fresh snapshot. */
     maxAttempts?: number;
     threshold(input: AgentSnapshot): boolean | Promise<boolean>;

package/dist/agent-runtime/compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAA4B,MAAM,SAAS,CAAC;AAG3E,MAAM,WAAW,sBAAsB,CAAC,OAAO;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B,CAAC,cAAc,SAAS,OAAO;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,SAAS,CACP,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GACvD,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IAC9D,oBAAoB,CAAC,KAAK,EAAE;QAC1B,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACjC,iBAAiB,EAAE,SAAS,YAAY,EAAE,CAAC;KAC5C,GAAG,YAAY,CAAC;IACjB,mBAAmB,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAClF,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAuED,wBAAgB,oBAAoB,CAAC,cAAc,SAAS,OAAO,EACjE,MAAM,EAAE,0BAA0B,CAAC,cAAc,CAAC,WAU7B;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;CAC3C,KAAG,OAAO,CAAC,qBAAqB,CAAC,CA0DnC"}
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAA4B,MAAM,SAAS,CAAC;AAC3E,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,sBAAsB,CAAC,OAAO;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B,CAAC,cAAc,SAAS,OAAO;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,SAAS,CACP,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GACvD,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IAC9D,oBAAoB,CAAC,KAAK,EAAE;QAC1B,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACjC,iBAAiB,EAAE,SAAS,YAAY,EAAE,CAAC;KAC5C,GAAG,YAAY,CAAC;IACjB,mBAAmB,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAClF,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAwDD,wBAAgB,oBAAoB,CAAC,cAAc,SAAS,OAAO,EACjE,MAAM,EAAE,0BAA0B,CAAC,cAAc,CAAC,WAU7B;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;CAC3C,KAAG,OAAO,CAAC,qBAAqB,CAAC,CA2DnC"}

package/dist/agent-runtime/contained-files.d.ts

@@ -0,0 +1,31 @@
+export interface ContainedFile {
+    absolute: string;
+    relative: string;
+}
+export interface ContainedFileScan {
+    files: readonly ContainedFile[];
+    truncated: boolean;
+    skippedDirectories: number;
+    skippedSymlinks: number;
+}
+/** Open the final path without following a replacement symlink and allocate only within budget. */
+export declare function readContainedUtf8File(absolute: string, maxBytes: number): Promise<{
+    text: string;
+    bytes: number;
+    mode: number;
+}>;
+/** One deterministic, symlink-refusing walker for harness resources and workspace search. */
+export declare function walkContainedFiles(input: {
+    root: string;
+    maxDepth: number;
+    maxFiles: number;
+}): Promise<readonly ContainedFile[]>;
+/** Bounded workspace scan that can omit known trees and symlinks without following either. */
+export declare function scanContainedFiles(input: {
+    root: string;
+    maxDepth: number;
+    maxFiles: number;
+    symlinks: 'refuse' | 'skip';
+    excludeDirectory?: (relative: string) => boolean;
+}): Promise<ContainedFileScan>;
+//# sourceMappingURL=contained-files.d.ts.map

package/dist/agent-runtime/contained-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contained-files.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/contained-files.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,mGAAmG;AACnG,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA2BxD;AAOD,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAIpC;AAED,8FAA8F;AAC9F,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAClD,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+C7B"}