@sammorrowdrums/mcpi-agent-core 0.85.0-bootstrap.0

package/dist/harness/types.d.ts

@@ -0,0 +1,228 @@
+import type { SimpleStreamOptions, Transport } from "@sammorrowdrums/mcpi-ai";
+import type { Static, TSchema } from "typebox";
+import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "../types.ts";
+/** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */
+export type Result<TValue, TError> = {
+    ok: true;
+    value: TValue;
+} | {
+    ok: false;
+    error: TError;
+};
+/** Create a successful {@link Result}. */
+export declare function ok<TValue, TError>(value: TValue): Result<TValue, TError>;
+/** Create a failed {@link Result}. */
+export declare function err<TValue, TError>(error: TError): Result<TValue, TError>;
+/** Return the success value or throw the failure error. Intended for tests and explicit adapter boundaries. */
+export declare function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue;
+/** Return the success value or `undefined`. Only object values are allowed to avoid truthiness bugs with primitives. */
+export declare function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined;
+/** Normalize unknown thrown values into Error instances before using them as typed error causes. */
+export declare function toError(error: unknown): Error;
+/**
+ * Skill loaded from a `SKILL.md` file or provided by an application.
+ *
+ * `name`, `description`, and `filePath` are inserted into the system prompt in an XML-formatted block as suggested by agentskills.io.
+ * Use {@link formatSkillsForSystemPrompt} to generate the spec-compatible system prompt block.
+ */
+export interface Skill {
+    /** Stable skill name used for lookup and model-visible listings. */
+    name: string;
+    /** Short model-visible description of when to use the skill. */
+    description: string;
+    /** Full skill instructions. */
+    content: string;
+    /** Absolute path to the skill file. Used for model-visible location and resolving relative references. */
+    filePath: string;
+    /** Exclude this skill from model-visible skill lists while still allowing explicit application invocation. */
+    disableModelInvocation?: boolean;
+}
+/** Prompt template that can be formatted into a prompt for explicit invocation. */
+export interface PromptTemplate {
+    /** Stable template name used for lookup or application command routing. */
+    name: string;
+    /** Optional description for command lists or autocomplete. */
+    description?: string;
+    /** Template content. Argument placeholders are formatted by `formatPromptTemplateInvocation`. */
+    content: string;
+}
+/** Resources made available to explicit invocation methods and system-prompt callbacks. */
+export interface AgentHarnessResources<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
+    /** Prompt templates available for explicit invocation. */
+    promptTemplates?: TPromptTemplate[];
+    /** Skills available to the model and explicit skill invocation. */
+    skills?: TSkill[];
+}
+/** Tool definition executed by an {@link AgentHarness} with an application-defined context. */
+export type AgentHarnessTool<TContext extends object | undefined, TParameters extends TSchema = TSchema, TDetails = unknown> = Omit<AgentTool<TParameters, TDetails>, "execute"> & {
+    /** Execute the tool call with the context resolved for the current turn snapshot. */
+    execute(toolCallId: string, params: Static<TParameters>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, context: TContext): Promise<AgentToolResult<TDetails>>;
+};
+/** Static tool context or zero-argument provider resolved for each turn snapshot. */
+export type AgentHarnessToolContextSource<TContext extends object | undefined> = TContext | (() => TContext | Promise<TContext>);
+/** Curated provider request options owned by the harness and snapshotted per turn. */
+export interface AgentHarnessStreamOptions {
+    /** Preferred transport forwarded to the stream function. */
+    transport?: Transport;
+    /** Provider request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum provider retry attempts. */
+    maxRetries?: number;
+    /** Optional cap for provider-requested retry delays. */
+    maxRetryDelayMs?: number;
+    /** Additional request headers merged with auth and lifecycle headers. */
+    headers?: Record<string, string>;
+    /** Provider metadata forwarded with requests. */
+    metadata?: SimpleStreamOptions["metadata"];
+    /** Provider cache retention hint. */
+    cacheRetention?: SimpleStreamOptions["cacheRetention"];
+}
+/** Per-request stream option patch returned by provider hooks. */
+export interface AgentHarnessStreamOptionsPatch extends Omit<Partial<AgentHarnessStreamOptions>, "headers" | "metadata"> {
+    /** Header patch. `undefined` values delete keys; explicit `headers: undefined` clears all headers. */
+    headers?: Record<string, string | undefined>;
+    /** Metadata patch. `undefined` values delete keys; explicit `metadata: undefined` clears all metadata. */
+    metadata?: Record<string, unknown | undefined>;
+}
+/** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */
+export type FileKind = "file" | "directory" | "symlink";
+/** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported" | "unknown";
+/** Error returned by {@link FileSystem} file operations. */
+export declare class FileError extends Error {
+    /** Backend-independent error code. */
+    code: FileErrorCode;
+    /** Absolute addressed path associated with the failure, when available. */
+    path?: string;
+    constructor(code: FileErrorCode, message: string, path?: string, cause?: Error);
+}
+/** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */
+export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "callback_error" | "unknown";
+/** Error returned by {@link ExecutionEnv.exec}. */
+export declare class ExecutionError extends Error {
+    /** Backend-independent error code. */
+    code: ExecutionErrorCode;
+    constructor(code: ExecutionErrorCode, message: string, cause?: Error);
+}
+/** Stable compaction error codes returned by compaction helpers. */
+export type CompactionErrorCode = "aborted" | "summarization_failed";
+/** Error returned by compaction helpers. */
+export declare class CompactionError extends Error {
+    /** Backend-independent error code. */
+    code: CompactionErrorCode;
+    constructor(code: CompactionErrorCode, message: string, cause?: Error);
+}
+/** Stable branch-summary error codes returned by branch summarization helpers. */
+export type BranchSummaryErrorCode = "aborted" | "summarization_failed";
+/** Error returned by branch summarization helpers. */
+export declare class BranchSummaryError extends Error {
+    /** Backend-independent error code. */
+    code: BranchSummaryErrorCode;
+    constructor(code: BranchSummaryErrorCode, message: string, cause?: Error);
+}
+/** Metadata for one filesystem object in a {@link FileSystem}. */
+export interface FileInfo {
+    /** Basename of {@link path}. */
+    name: string;
+    /** Absolute, syntactically normalized addressed path in the execution environment. Symlinks are not followed. */
+    path: string;
+    /** Object kind. Symlink targets are not followed; use {@link FileSystem.canonicalPath} explicitly. */
+    kind: FileKind;
+    /** Size in bytes for the addressed filesystem object. */
+    size: number;
+    /** Modification time as milliseconds since Unix epoch. */
+    mtimeMs: number;
+}
+/**
+ * Filesystem capability used by the harness.
+ *
+ * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by file operations are addressed paths
+ * in the filesystem namespace, but are not canonicalized through symlinks unless returned by {@link canonicalPath}.
+ *
+ * Operation methods must never throw or reject. All filesystem failures, including unexpected backend failures, must be
+ * encoded in the returned {@link Result}. Implementations must preserve this invariant.
+ */
+export interface FileSystem {
+    /** Current working directory for relative paths. */
+    cwd: string;
+    /** Return an absolute addressed path without requiring it to exist and without resolving symlinks. */
+    absolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Join path segments in the filesystem namespace without requiring the result to exist. */
+    joinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Read a UTF-8 text file. */
+    readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Read UTF-8 text lines. Implementations should stop once `maxLines` lines have been read. */
+    readTextLines(path: string, options?: {
+        maxLines?: number;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string[], FileError>>;
+    /** Read a binary file. */
+    readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** Create or overwrite a file, creating parent directories when supported. */
+    writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Create or append to a file, creating parent directories when supported. */
+    appendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Atomically rename a file, replacing the destination when it exists. Does not copy across filesystems. */
+    renameFile(sourcePath: string, destinationPath: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Return metadata for the addressed path without following symlinks. */
+    fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+    /** List direct children of a directory without following symlinks. */
+    listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+    /** Return the canonical path for an existing path, resolving symlinks where supported. */
+    canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
+    exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** Create a directory. Defaults: `recursive: true`, no abort signal. */
+    createDir(path: string, options?: {
+        recursive?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    /** Remove a file or directory. Defaults: `recursive: false`, `force: false`, no abort signal. */
+    remove(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    /** Create a temporary directory and return its absolute path. Defaults: `prefix: "tmp-"`, no abort signal. */
+    createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Create a temporary file and return its absolute path. Defaults: `prefix: ""`, `suffix: ""`, no abort signal. */
+    createTempFile(options?: {
+        prefix?: string;
+        suffix?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string, FileError>>;
+    /** Release filesystem resources. Must be best-effort and must not throw or reject. */
+    cleanup(): Promise<void>;
+}
+/** Options for {@link Shell.exec}. */
+export interface ShellExecOptions {
+    /** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */
+    cwd?: string;
+    /** Environment variables for the command. Values override inherited defaults when `inheritEnv` is true. */
+    env?: Record<string, string>;
+    /** Whether to inherit the execution environment's default variables. Defaults to true. */
+    inheritEnv?: boolean;
+    /** Timeout in seconds. Implementations should return a timeout error when the command exceeds this duration. Defaults to no timeout. */
+    timeout?: number;
+    /** Abort signal used to terminate the command. Defaults to no abort signal. */
+    abortSignal?: AbortSignal;
+    /** Called with stdout chunks as they are produced. */
+    onStdout?: (chunk: string) => void;
+    /** Called with stderr chunks as they are produced. */
+    onStderr?: (chunk: string) => void;
+}
+/** Shell execution capability used by the harness. */
+export interface Shell {
+    /** Execute a shell command in {@link FileSystem.cwd} unless `options.cwd` is provided. */
+    exec(command: string, options?: ShellExecOptions): Promise<Result<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }, ExecutionError>>;
+    /** Release shell resources. Must be best-effort and must not throw or reject. */
+    cleanup(): Promise<void>;
+}
+/** Filesystem and process execution environment used by the harness. */
+export interface ExecutionEnv extends FileSystem, Shell {
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/harness/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/harness/types.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SimpleStreamOptions, Transport } from \"@sammorrowdrums/mcpi-ai\";\nimport type { Static, TSchema } from \"typebox\";\nimport type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from \"../types.ts\";\n\n/** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */\nexport type Result<TValue, TError> = { ok: true; value: TValue } | { ok: false; error: TError };\n\n/** Create a successful {@link Result}. */\nexport function ok<TValue, TError>(value: TValue): Result<TValue, TError> {\n\treturn { ok: true, value };\n}\n\n/** Create a failed {@link Result}. */\nexport function err<TValue, TError>(error: TError): Result<TValue, TError> {\n\treturn { ok: false, error };\n}\n\n/** Return the success value or throw the failure error. Intended for tests and explicit adapter boundaries. */\nexport function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue {\n\tif (!result.ok) throw result.error;\n\treturn result.value;\n}\n\n/** Return the success value or `undefined`. Only object values are allowed to avoid truthiness bugs with primitives. */\nexport function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined {\n\treturn result.ok ? result.value : undefined;\n}\n\n/** Normalize unknown thrown values into Error instances before using them as typed error causes. */\nexport function toError(error: unknown): Error {\n\tif (error instanceof Error) return error;\n\tif (typeof error === \"string\") return new Error(error);\n\ttry {\n\t\treturn new Error(JSON.stringify(error));\n\t} catch {\n\t\treturn new Error(String(error));\n\t}\n}\n\n/**\n * Skill loaded from a `SKILL.md` file or provided by an application.\n *\n * `name`, `description`, and `filePath` are inserted into the system prompt in an XML-formatted block as suggested by agentskills.io.\n * Use {@link formatSkillsForSystemPrompt} to generate the spec-compatible system prompt block.\n */\nexport interface Skill {\n\t/** Stable skill name used for lookup and model-visible listings. */\n\tname: string;\n\t/** Short model-visible description of when to use the skill. */\n\tdescription: string;\n\t/** Full skill instructions. */\n\tcontent: string;\n\t/** Absolute path to the skill file. Used for model-visible location and resolving relative references. */\n\tfilePath: string;\n\t/** Exclude this skill from model-visible skill lists while still allowing explicit application invocation. */\n\tdisableModelInvocation?: boolean;\n}\n\n/** Prompt template that can be formatted into a prompt for explicit invocation. */\nexport interface PromptTemplate {\n\t/** Stable template name used for lookup or application command routing. */\n\tname: string;\n\t/** Optional description for command lists or autocomplete. */\n\tdescription?: string;\n\t/** Template content. Argument placeholders are formatted by `formatPromptTemplateInvocation`. */\n\tcontent: string;\n}\n\n/** Resources made available to explicit invocation methods and system-prompt callbacks. */\nexport interface AgentHarnessResources<\n\tTSkill extends Skill = Skill,\n\tTPromptTemplate extends PromptTemplate = PromptTemplate,\n> {\n\t/** Prompt templates available for explicit invocation. */\n\tpromptTemplates?: TPromptTemplate[];\n\t/** Skills available to the model and explicit skill invocation. */\n\tskills?: TSkill[];\n}\n\n/** Tool definition executed by an {@link AgentHarness} with an application-defined context. */\nexport type AgentHarnessTool<\n\tTContext extends object | undefined,\n\tTParameters extends TSchema = TSchema,\n\tTDetails = unknown,\n> = Omit<AgentTool<TParameters, TDetails>, \"execute\"> & {\n\t/** Execute the tool call with the context resolved for the current turn snapshot. */\n\texecute(\n\t\ttoolCallId: string,\n\t\tparams: Static<TParameters>,\n\t\tsignal: AbortSignal | undefined,\n\t\tonUpdate: AgentToolUpdateCallback<TDetails> | undefined,\n\t\tcontext: TContext,\n\t): Promise<AgentToolResult<TDetails>>;\n};\n\n/** Static tool context or zero-argument provider resolved for each turn snapshot. */\nexport type AgentHarnessToolContextSource<TContext extends object | undefined> =\n\t| TContext\n\t| (() => TContext | Promise<TContext>);\n\n/** Curated provider request options owned by the harness and snapshotted per turn. */\nexport interface AgentHarnessStreamOptions {\n\t/** Preferred transport forwarded to the stream function. */\n\ttransport?: Transport;\n\t/** Provider request timeout in milliseconds. */\n\ttimeoutMs?: number;\n\t/** Maximum provider retry attempts. */\n\tmaxRetries?: number;\n\t/** Optional cap for provider-requested retry delays. */\n\tmaxRetryDelayMs?: number;\n\t/** Additional request headers merged with auth and lifecycle headers. */\n\theaders?: Record<string, string>;\n\t/** Provider metadata forwarded with requests. */\n\tmetadata?: SimpleStreamOptions[\"metadata\"];\n\t/** Provider cache retention hint. */\n\tcacheRetention?: SimpleStreamOptions[\"cacheRetention\"];\n}\n\n/** Per-request stream option patch returned by provider hooks. */\nexport interface AgentHarnessStreamOptionsPatch\n\textends Omit<Partial<AgentHarnessStreamOptions>, \"headers\" | \"metadata\"> {\n\t/** Header patch. `undefined` values delete keys; explicit `headers: undefined` clears all headers. */\n\theaders?: Record<string, string | undefined>;\n\t/** Metadata patch. `undefined` values delete keys; explicit `metadata: undefined` clears all metadata. */\n\tmetadata?: Record<string, unknown | undefined>;\n}\n\n/** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */\nexport type FileKind = \"file\" | \"directory\" | \"symlink\";\n\n/** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */\nexport type FileErrorCode =\n\t| \"aborted\"\n\t| \"not_found\"\n\t| \"permission_denied\"\n\t| \"not_directory\"\n\t| \"is_directory\"\n\t| \"invalid\"\n\t| \"not_supported\"\n\t| \"unknown\";\n\n/** Error returned by {@link FileSystem} file operations. */\nexport class FileError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: FileErrorCode;\n\t/** Absolute addressed path associated with the failure, when available. */\n\tpublic path?: string;\n\n\tconstructor(code: FileErrorCode, message: string, path?: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"FileError\";\n\t\tthis.code = code;\n\t\tthis.path = path;\n\t}\n}\n\n/** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */\nexport type ExecutionErrorCode =\n\t| \"aborted\"\n\t| \"timeout\"\n\t| \"shell_unavailable\"\n\t| \"spawn_error\"\n\t| \"callback_error\"\n\t| \"unknown\";\n\n/** Error returned by {@link ExecutionEnv.exec}. */\nexport class ExecutionError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: ExecutionErrorCode;\n\n\tconstructor(code: ExecutionErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"ExecutionError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Stable compaction error codes returned by compaction helpers. */\nexport type CompactionErrorCode = \"aborted\" | \"summarization_failed\";\n\n/** Error returned by compaction helpers. */\nexport class CompactionError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: CompactionErrorCode;\n\n\tconstructor(code: CompactionErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"CompactionError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Stable branch-summary error codes returned by branch summarization helpers. */\nexport type BranchSummaryErrorCode = \"aborted\" | \"summarization_failed\";\n\n/** Error returned by branch summarization helpers. */\nexport class BranchSummaryError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: BranchSummaryErrorCode;\n\n\tconstructor(code: BranchSummaryErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"BranchSummaryError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Metadata for one filesystem object in a {@link FileSystem}. */\nexport interface FileInfo {\n\t/** Basename of {@link path}. */\n\tname: string;\n\t/** Absolute, syntactically normalized addressed path in the execution environment. Symlinks are not followed. */\n\tpath: string;\n\t/** Object kind. Symlink targets are not followed; use {@link FileSystem.canonicalPath} explicitly. */\n\tkind: FileKind;\n\t/** Size in bytes for the addressed filesystem object. */\n\tsize: number;\n\t/** Modification time as milliseconds since Unix epoch. */\n\tmtimeMs: number;\n}\n\n/**\n * Filesystem capability used by the harness.\n *\n * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by file operations are addressed paths\n * in the filesystem namespace, but are not canonicalized through symlinks unless returned by {@link canonicalPath}.\n *\n * Operation methods must never throw or reject. All filesystem failures, including unexpected backend failures, must be\n * encoded in the returned {@link Result}. Implementations must preserve this invariant.\n */\nexport interface FileSystem {\n\t/** Current working directory for relative paths. */\n\tcwd: string;\n\n\t/** Return an absolute addressed path without requiring it to exist and without resolving symlinks. */\n\tabsolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Join path segments in the filesystem namespace without requiring the result to exist. */\n\tjoinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Read a UTF-8 text file. */\n\treadTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Read UTF-8 text lines. Implementations should stop once `maxLines` lines have been read. */\n\treadTextLines(\n\t\tpath: string,\n\t\toptions?: { maxLines?: number; abortSignal?: AbortSignal },\n\t): Promise<Result<string[], FileError>>;\n\t/** Read a binary file. */\n\treadBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;\n\t/** Create or overwrite a file, creating parent directories when supported. */\n\twriteFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;\n\t/** Create or append to a file, creating parent directories when supported. */\n\tappendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;\n\t/** Atomically rename a file, replacing the destination when it exists. Does not copy across filesystems. */\n\trenameFile(sourcePath: string, destinationPath: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;\n\t/** Return metadata for the addressed path without following symlinks. */\n\tfileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;\n\t/** List direct children of a directory without following symlinks. */\n\tlistDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;\n\t/** Return the canonical path for an existing path, resolving symlinks where supported. */\n\tcanonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */\n\texists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;\n\t/** Create a directory. Defaults: `recursive: true`, no abort signal. */\n\tcreateDir(\n\t\tpath: string,\n\t\toptions?: { recursive?: boolean; abortSignal?: AbortSignal },\n\t): Promise<Result<void, FileError>>;\n\t/** Remove a file or directory. Defaults: `recursive: false`, `force: false`, no abort signal. */\n\tremove(\n\t\tpath: string,\n\t\toptions?: { recursive?: boolean; force?: boolean; abortSignal?: AbortSignal },\n\t): Promise<Result<void, FileError>>;\n\t/** Create a temporary directory and return its absolute path. Defaults: `prefix: \"tmp-\"`, no abort signal. */\n\tcreateTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Create a temporary file and return its absolute path. Defaults: `prefix: \"\"`, `suffix: \"\"`, no abort signal. */\n\tcreateTempFile(options?: {\n\t\tprefix?: string;\n\t\tsuffix?: string;\n\t\tabortSignal?: AbortSignal;\n\t}): Promise<Result<string, FileError>>;\n\n\t/** Release filesystem resources. Must be best-effort and must not throw or reject. */\n\tcleanup(): Promise<void>;\n}\n\n/** Options for {@link Shell.exec}. */\nexport interface ShellExecOptions {\n\t/** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */\n\tcwd?: string;\n\t/** Environment variables for the command. Values override inherited defaults when `inheritEnv` is true. */\n\tenv?: Record<string, string>;\n\t/** Whether to inherit the execution environment's default variables. Defaults to true. */\n\tinheritEnv?: boolean;\n\t/** Timeout in seconds. Implementations should return a timeout error when the command exceeds this duration. Defaults to no timeout. */\n\ttimeout?: number;\n\t/** Abort signal used to terminate the command. Defaults to no abort signal. */\n\tabortSignal?: AbortSignal;\n\t/** Called with stdout chunks as they are produced. */\n\tonStdout?: (chunk: string) => void;\n\t/** Called with stderr chunks as they are produced. */\n\tonStderr?: (chunk: string) => void;\n}\n\n/** Shell execution capability used by the harness. */\nexport interface Shell {\n\t/** Execute a shell command in {@link FileSystem.cwd} unless `options.cwd` is provided. */\n\texec(\n\t\tcommand: string,\n\t\toptions?: ShellExecOptions,\n\t): Promise<Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>>;\n\t/** Release shell resources. Must be best-effort and must not throw or reject. */\n\tcleanup(): Promise<void>;\n}\n\n/** Filesystem and process execution environment used by the harness. */\nexport interface ExecutionEnv extends FileSystem, Shell {}\n"]}

package/dist/harness/types.js

@@ -0,0 +1,75 @@
+/** Create a successful {@link Result}. */
+export function ok(value) {
+    return { ok: true, value };
+}
+/** Create a failed {@link Result}. */
+export function err(error) {
+    return { ok: false, error };
+}
+/** Return the success value or throw the failure error. Intended for tests and explicit adapter boundaries. */
+export function getOrThrow(result) {
+    if (!result.ok)
+        throw result.error;
+    return result.value;
+}
+/** Return the success value or `undefined`. Only object values are allowed to avoid truthiness bugs with primitives. */
+export function getOrUndefined(result) {
+    return result.ok ? result.value : undefined;
+}
+/** Normalize unknown thrown values into Error instances before using them as typed error causes. */
+export function toError(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error === "string")
+        return new Error(error);
+    try {
+        return new Error(JSON.stringify(error));
+    }
+    catch {
+        return new Error(String(error));
+    }
+}
+/** Error returned by {@link FileSystem} file operations. */
+export class FileError extends Error {
+    /** Backend-independent error code. */
+    code;
+    /** Absolute addressed path associated with the failure, when available. */
+    path;
+    constructor(code, message, path, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "FileError";
+        this.code = code;
+        this.path = path;
+    }
+}
+/** Error returned by {@link ExecutionEnv.exec}. */
+export class ExecutionError extends Error {
+    /** Backend-independent error code. */
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "ExecutionError";
+        this.code = code;
+    }
+}
+/** Error returned by compaction helpers. */
+export class CompactionError extends Error {
+    /** Backend-independent error code. */
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "CompactionError";
+        this.code = code;
+    }
+}
+/** Error returned by branch summarization helpers. */
+export class BranchSummaryError extends Error {
+    /** Backend-independent error code. */
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "BranchSummaryError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/harness/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/harness/types.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SimpleStreamOptions, Transport } from \"@sammorrowdrums/mcpi-ai\";\nimport type { Static, TSchema } from \"typebox\";\nimport type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from \"../types.ts\";\n\n/** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */\nexport type Result<TValue, TError> = { ok: true; value: TValue } | { ok: false; error: TError };\n\n/** Create a successful {@link Result}. */\nexport function ok<TValue, TError>(value: TValue): Result<TValue, TError> {\n\treturn { ok: true, value };\n}\n\n/** Create a failed {@link Result}. */\nexport function err<TValue, TError>(error: TError): Result<TValue, TError> {\n\treturn { ok: false, error };\n}\n\n/** Return the success value or throw the failure error. Intended for tests and explicit adapter boundaries. */\nexport function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue {\n\tif (!result.ok) throw result.error;\n\treturn result.value;\n}\n\n/** Return the success value or `undefined`. Only object values are allowed to avoid truthiness bugs with primitives. */\nexport function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined {\n\treturn result.ok ? result.value : undefined;\n}\n\n/** Normalize unknown thrown values into Error instances before using them as typed error causes. */\nexport function toError(error: unknown): Error {\n\tif (error instanceof Error) return error;\n\tif (typeof error === \"string\") return new Error(error);\n\ttry {\n\t\treturn new Error(JSON.stringify(error));\n\t} catch {\n\t\treturn new Error(String(error));\n\t}\n}\n\n/**\n * Skill loaded from a `SKILL.md` file or provided by an application.\n *\n * `name`, `description`, and `filePath` are inserted into the system prompt in an XML-formatted block as suggested by agentskills.io.\n * Use {@link formatSkillsForSystemPrompt} to generate the spec-compatible system prompt block.\n */\nexport interface Skill {\n\t/** Stable skill name used for lookup and model-visible listings. */\n\tname: string;\n\t/** Short model-visible description of when to use the skill. */\n\tdescription: string;\n\t/** Full skill instructions. */\n\tcontent: string;\n\t/** Absolute path to the skill file. Used for model-visible location and resolving relative references. */\n\tfilePath: string;\n\t/** Exclude this skill from model-visible skill lists while still allowing explicit application invocation. */\n\tdisableModelInvocation?: boolean;\n}\n\n/** Prompt template that can be formatted into a prompt for explicit invocation. */\nexport interface PromptTemplate {\n\t/** Stable template name used for lookup or application command routing. */\n\tname: string;\n\t/** Optional description for command lists or autocomplete. */\n\tdescription?: string;\n\t/** Template content. Argument placeholders are formatted by `formatPromptTemplateInvocation`. */\n\tcontent: string;\n}\n\n/** Resources made available to explicit invocation methods and system-prompt callbacks. */\nexport interface AgentHarnessResources<\n\tTSkill extends Skill = Skill,\n\tTPromptTemplate extends PromptTemplate = PromptTemplate,\n> {\n\t/** Prompt templates available for explicit invocation. */\n\tpromptTemplates?: TPromptTemplate[];\n\t/** Skills available to the model and explicit skill invocation. */\n\tskills?: TSkill[];\n}\n\n/** Tool definition executed by an {@link AgentHarness} with an application-defined context. */\nexport type AgentHarnessTool<\n\tTContext extends object | undefined,\n\tTParameters extends TSchema = TSchema,\n\tTDetails = unknown,\n> = Omit<AgentTool<TParameters, TDetails>, \"execute\"> & {\n\t/** Execute the tool call with the context resolved for the current turn snapshot. */\n\texecute(\n\t\ttoolCallId: string,\n\t\tparams: Static<TParameters>,\n\t\tsignal: AbortSignal | undefined,\n\t\tonUpdate: AgentToolUpdateCallback<TDetails> | undefined,\n\t\tcontext: TContext,\n\t): Promise<AgentToolResult<TDetails>>;\n};\n\n/** Static tool context or zero-argument provider resolved for each turn snapshot. */\nexport type AgentHarnessToolContextSource<TContext extends object | undefined> =\n\t| TContext\n\t| (() => TContext | Promise<TContext>);\n\n/** Curated provider request options owned by the harness and snapshotted per turn. */\nexport interface AgentHarnessStreamOptions {\n\t/** Preferred transport forwarded to the stream function. */\n\ttransport?: Transport;\n\t/** Provider request timeout in milliseconds. */\n\ttimeoutMs?: number;\n\t/** Maximum provider retry attempts. */\n\tmaxRetries?: number;\n\t/** Optional cap for provider-requested retry delays. */\n\tmaxRetryDelayMs?: number;\n\t/** Additional request headers merged with auth and lifecycle headers. */\n\theaders?: Record<string, string>;\n\t/** Provider metadata forwarded with requests. */\n\tmetadata?: SimpleStreamOptions[\"metadata\"];\n\t/** Provider cache retention hint. */\n\tcacheRetention?: SimpleStreamOptions[\"cacheRetention\"];\n}\n\n/** Per-request stream option patch returned by provider hooks. */\nexport interface AgentHarnessStreamOptionsPatch\n\textends Omit<Partial<AgentHarnessStreamOptions>, \"headers\" | \"metadata\"> {\n\t/** Header patch. `undefined` values delete keys; explicit `headers: undefined` clears all headers. */\n\theaders?: Record<string, string | undefined>;\n\t/** Metadata patch. `undefined` values delete keys; explicit `metadata: undefined` clears all metadata. */\n\tmetadata?: Record<string, unknown | undefined>;\n}\n\n/** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */\nexport type FileKind = \"file\" | \"directory\" | \"symlink\";\n\n/** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */\nexport type FileErrorCode =\n\t| \"aborted\"\n\t| \"not_found\"\n\t| \"permission_denied\"\n\t| \"not_directory\"\n\t| \"is_directory\"\n\t| \"invalid\"\n\t| \"not_supported\"\n\t| \"unknown\";\n\n/** Error returned by {@link FileSystem} file operations. */\nexport class FileError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: FileErrorCode;\n\t/** Absolute addressed path associated with the failure, when available. */\n\tpublic path?: string;\n\n\tconstructor(code: FileErrorCode, message: string, path?: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"FileError\";\n\t\tthis.code = code;\n\t\tthis.path = path;\n\t}\n}\n\n/** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */\nexport type ExecutionErrorCode =\n\t| \"aborted\"\n\t| \"timeout\"\n\t| \"shell_unavailable\"\n\t| \"spawn_error\"\n\t| \"callback_error\"\n\t| \"unknown\";\n\n/** Error returned by {@link ExecutionEnv.exec}. */\nexport class ExecutionError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: ExecutionErrorCode;\n\n\tconstructor(code: ExecutionErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"ExecutionError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Stable compaction error codes returned by compaction helpers. */\nexport type CompactionErrorCode = \"aborted\" | \"summarization_failed\";\n\n/** Error returned by compaction helpers. */\nexport class CompactionError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: CompactionErrorCode;\n\n\tconstructor(code: CompactionErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"CompactionError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Stable branch-summary error codes returned by branch summarization helpers. */\nexport type BranchSummaryErrorCode = \"aborted\" | \"summarization_failed\";\n\n/** Error returned by branch summarization helpers. */\nexport class BranchSummaryError extends Error {\n\t/** Backend-independent error code. */\n\tpublic code: BranchSummaryErrorCode;\n\n\tconstructor(code: BranchSummaryErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"BranchSummaryError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Metadata for one filesystem object in a {@link FileSystem}. */\nexport interface FileInfo {\n\t/** Basename of {@link path}. */\n\tname: string;\n\t/** Absolute, syntactically normalized addressed path in the execution environment. Symlinks are not followed. */\n\tpath: string;\n\t/** Object kind. Symlink targets are not followed; use {@link FileSystem.canonicalPath} explicitly. */\n\tkind: FileKind;\n\t/** Size in bytes for the addressed filesystem object. */\n\tsize: number;\n\t/** Modification time as milliseconds since Unix epoch. */\n\tmtimeMs: number;\n}\n\n/**\n * Filesystem capability used by the harness.\n *\n * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by file operations are addressed paths\n * in the filesystem namespace, but are not canonicalized through symlinks unless returned by {@link canonicalPath}.\n *\n * Operation methods must never throw or reject. All filesystem failures, including unexpected backend failures, must be\n * encoded in the returned {@link Result}. Implementations must preserve this invariant.\n */\nexport interface FileSystem {\n\t/** Current working directory for relative paths. */\n\tcwd: string;\n\n\t/** Return an absolute addressed path without requiring it to exist and without resolving symlinks. */\n\tabsolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Join path segments in the filesystem namespace without requiring the result to exist. */\n\tjoinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Read a UTF-8 text file. */\n\treadTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Read UTF-8 text lines. Implementations should stop once `maxLines` lines have been read. */\n\treadTextLines(\n\t\tpath: string,\n\t\toptions?: { maxLines?: number; abortSignal?: AbortSignal },\n\t): Promise<Result<string[], FileError>>;\n\t/** Read a binary file. */\n\treadBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;\n\t/** Create or overwrite a file, creating parent directories when supported. */\n\twriteFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;\n\t/** Create or append to a file, creating parent directories when supported. */\n\tappendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;\n\t/** Atomically rename a file, replacing the destination when it exists. Does not copy across filesystems. */\n\trenameFile(sourcePath: string, destinationPath: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;\n\t/** Return metadata for the addressed path without following symlinks. */\n\tfileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;\n\t/** List direct children of a directory without following symlinks. */\n\tlistDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;\n\t/** Return the canonical path for an existing path, resolving symlinks where supported. */\n\tcanonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */\n\texists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;\n\t/** Create a directory. Defaults: `recursive: true`, no abort signal. */\n\tcreateDir(\n\t\tpath: string,\n\t\toptions?: { recursive?: boolean; abortSignal?: AbortSignal },\n\t): Promise<Result<void, FileError>>;\n\t/** Remove a file or directory. Defaults: `recursive: false`, `force: false`, no abort signal. */\n\tremove(\n\t\tpath: string,\n\t\toptions?: { recursive?: boolean; force?: boolean; abortSignal?: AbortSignal },\n\t): Promise<Result<void, FileError>>;\n\t/** Create a temporary directory and return its absolute path. Defaults: `prefix: \"tmp-\"`, no abort signal. */\n\tcreateTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;\n\t/** Create a temporary file and return its absolute path. Defaults: `prefix: \"\"`, `suffix: \"\"`, no abort signal. */\n\tcreateTempFile(options?: {\n\t\tprefix?: string;\n\t\tsuffix?: string;\n\t\tabortSignal?: AbortSignal;\n\t}): Promise<Result<string, FileError>>;\n\n\t/** Release filesystem resources. Must be best-effort and must not throw or reject. */\n\tcleanup(): Promise<void>;\n}\n\n/** Options for {@link Shell.exec}. */\nexport interface ShellExecOptions {\n\t/** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */\n\tcwd?: string;\n\t/** Environment variables for the command. Values override inherited defaults when `inheritEnv` is true. */\n\tenv?: Record<string, string>;\n\t/** Whether to inherit the execution environment's default variables. Defaults to true. */\n\tinheritEnv?: boolean;\n\t/** Timeout in seconds. Implementations should return a timeout error when the command exceeds this duration. Defaults to no timeout. */\n\ttimeout?: number;\n\t/** Abort signal used to terminate the command. Defaults to no abort signal. */\n\tabortSignal?: AbortSignal;\n\t/** Called with stdout chunks as they are produced. */\n\tonStdout?: (chunk: string) => void;\n\t/** Called with stderr chunks as they are produced. */\n\tonStderr?: (chunk: string) => void;\n}\n\n/** Shell execution capability used by the harness. */\nexport interface Shell {\n\t/** Execute a shell command in {@link FileSystem.cwd} unless `options.cwd` is provided. */\n\texec(\n\t\tcommand: string,\n\t\toptions?: ShellExecOptions,\n\t): Promise<Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>>;\n\t/** Release shell resources. Must be best-effort and must not throw or reject. */\n\tcleanup(): Promise<void>;\n}\n\n/** Filesystem and process execution environment used by the harness. */\nexport interface ExecutionEnv extends FileSystem, Shell {}\n"]}

package/dist/harness/utils/shell-output.d.ts

@@ -0,0 +1,22 @@
+import { type ExecutionEnv, ExecutionError, type Result, type ShellExecOptions } from "../types.ts";
+import { type TruncationResult } from "./truncate.ts";
+export interface ShellCaptureProgress {
+    output: string;
+    truncation: TruncationResult;
+    fullOutputPath?: string;
+    lastLineBytes: number;
+}
+export interface ShellCaptureOptions extends Omit<ShellExecOptions, "onStdout" | "onStderr"> {
+    onChunk?: (chunk: string, getProgress: () => ShellCaptureProgress) => void;
+    /** Return shell execution failures with captured output instead of as a failed Result. */
+    returnExecutionErrors?: boolean;
+}
+export interface ShellCaptureResult extends ShellCaptureProgress {
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    executionError?: ExecutionError;
+}
+export declare function sanitizeBinaryOutput(str: string): string;
+export declare function executeShellWithCapture(env: ExecutionEnv, command: string, options?: ShellCaptureOptions): Promise<Result<ShellCaptureResult, ExecutionError>>;
+//# sourceMappingURL=shell-output.d.ts.map

package/dist/harness/utils/shell-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-output.d.ts","sourceRoot":"","sources":["../../../src/harness/utils/shell-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,cAAc,EAAW,KAAK,MAAM,EAAE,KAAK,gBAAgB,EAAW,MAAM,aAAa,CAAC;AACtH,OAAO,EAAwC,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAE1G,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,UAAU,CAAC;IAC3F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,KAAK,IAAI,CAAC;IAC3E,0FAA0F;IAC1F,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC/D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;CAChC;AAQD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWxD;AAUD,wBAAsB,uBAAuB,CAC5C,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC,CA4IrD","sourcesContent":["import { type ExecutionEnv, ExecutionError, err, ok, type Result, type ShellExecOptions, toError } from \"../types.ts\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateTail } from \"./truncate.ts\";\n\nexport interface ShellCaptureProgress {\n\toutput: string;\n\ttruncation: TruncationResult;\n\tfullOutputPath?: string;\n\tlastLineBytes: number;\n}\n\nexport interface ShellCaptureOptions extends Omit<ShellExecOptions, \"onStdout\" | \"onStderr\"> {\n\tonChunk?: (chunk: string, getProgress: () => ShellCaptureProgress) => void;\n\t/** Return shell execution failures with captured output instead of as a failed Result. */\n\treturnExecutionErrors?: boolean;\n}\n\nexport interface ShellCaptureResult extends ShellCaptureProgress {\n\texitCode: number | undefined;\n\tcancelled: boolean;\n\ttruncated: boolean;\n\texecutionError?: ExecutionError;\n}\n\nfunction toExecutionError(error: unknown): ExecutionError {\n\tif (error instanceof ExecutionError) return error;\n\tconst cause = toError(error);\n\treturn new ExecutionError(\"unknown\", cause.message, cause);\n}\n\nexport function sanitizeBinaryOutput(str: string): string {\n\treturn Array.from(str)\n\t\t.filter((char) => {\n\t\t\tconst code = char.codePointAt(0);\n\t\t\tif (code === undefined) return false;\n\t\t\tif (code === 0x09 || code === 0x0a || code === 0x0d) return true;\n\t\t\tif (code <= 0x1f) return false;\n\t\t\tif (code >= 0xfff9 && code <= 0xfffb) return false;\n\t\t\treturn true;\n\t\t})\n\t\t.join(\"\");\n}\n\nfunction trimToLastUtf8Bytes(text: string, maxBytes: number, encoder: { encode(input?: string): Uint8Array }): string {\n\tconst bytes = encoder.encode(text);\n\tif (bytes.byteLength <= maxBytes) return text;\n\tlet start = bytes.byteLength - maxBytes;\n\twhile (start < bytes.byteLength && ((bytes[start] ?? 0) & 0xc0) === 0x80) start++;\n\treturn new TextDecoder().decode(bytes.subarray(start));\n}\n\nexport async function executeShellWithCapture(\n\tenv: ExecutionEnv,\n\tcommand: string,\n\toptions?: ShellCaptureOptions,\n): Promise<Result<ShellCaptureResult, ExecutionError>> {\n\tlet tailOutput = \"\";\n\tconst maxOutputBytes = DEFAULT_MAX_BYTES * 2;\n\tconst encoder = new TextEncoder();\n\n\tlet totalBytes = 0;\n\tlet completedLines = 0;\n\tlet hasOpenLine = false;\n\tlet currentLineBytes = 0;\n\tlet fullOutputPath: string | undefined;\n\tlet fullOutputRequested = false;\n\tlet acceptingOutput = true;\n\tlet writeChain: Promise<Result<void, ExecutionError>> = Promise.resolve(ok(undefined));\n\tlet captureError: ExecutionError | undefined;\n\n\tconst appendFullOutput = (text: string): void => {\n\t\tif (!fullOutputRequested || captureError) return;\n\t\twriteChain = writeChain.then(async (previous) => {\n\t\t\tif (!previous.ok) return previous;\n\t\t\tif (!fullOutputPath) return err(new ExecutionError(\"unknown\", \"Full output path was not created\"));\n\t\t\tconst appendResult = await env.appendFile(fullOutputPath, text);\n\t\t\treturn appendResult.ok ? ok(undefined) : err(toExecutionError(appendResult.error));\n\t\t});\n\t};\n\n\tconst ensureFullOutputFile = (initialContent: string): void => {\n\t\tif (fullOutputRequested || captureError) return;\n\t\tfullOutputRequested = true;\n\t\twriteChain = writeChain.then(async (previous) => {\n\t\t\tif (!previous.ok) return previous;\n\t\t\tconst tempFile = await env.createTempFile({ prefix: \"bash-\", suffix: \".log\" });\n\t\t\tif (!tempFile.ok) return err(toExecutionError(tempFile.error));\n\t\t\tfullOutputPath = tempFile.value;\n\t\t\tconst appendResult = await env.appendFile(tempFile.value, initialContent);\n\t\t\treturn appendResult.ok ? ok(undefined) : err(toExecutionError(appendResult.error));\n\t\t});\n\t};\n\n\tconst createProgress = (): ShellCaptureProgress => {\n\t\tconst tailTruncation = truncateTail(tailOutput);\n\t\tconst totalLines = completedLines + (hasOpenLine ? 1 : 0);\n\t\tconst truncated = totalLines > DEFAULT_MAX_LINES || totalBytes > DEFAULT_MAX_BYTES;\n\t\tconst truncation: TruncationResult = {\n\t\t\t...tailTruncation,\n\t\t\ttruncated,\n\t\t\ttruncatedBy: truncated\n\t\t\t\t? (tailTruncation.truncatedBy ?? (totalBytes > DEFAULT_MAX_BYTES ? \"bytes\" : \"lines\"))\n\t\t\t\t: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t};\n\t\treturn {\n\t\t\toutput: truncated ? truncation.content : tailOutput,\n\t\t\ttruncation,\n\t\t\tfullOutputPath,\n\t\t\tlastLineBytes: currentLineBytes,\n\t\t};\n\t};\n\n\tconst onChunk = (chunk: string): void => {\n\t\tif (!acceptingOutput) return;\n\t\ttry {\n\t\t\tconst text = sanitizeBinaryOutput(chunk).replace(/\\r/g, \"\");\n\t\t\tconst textBytes = encoder.encode(text).byteLength;\n\t\t\ttotalBytes += textBytes;\n\t\t\tconst newlineCount = text.split(\"\\n\").length - 1;\n\t\t\tcompletedLines += newlineCount;\n\t\t\tconst lastNewline = text.lastIndexOf(\"\\n\");\n\t\t\tif (lastNewline >= 0) {\n\t\t\t\tconst trailingText = text.slice(lastNewline + 1);\n\t\t\t\tcurrentLineBytes = encoder.encode(trailingText).byteLength;\n\t\t\t\thasOpenLine = trailingText.length > 0;\n\t\t\t} else if (text.length > 0) {\n\t\t\t\tcurrentLineBytes += textBytes;\n\t\t\t\thasOpenLine = true;\n\t\t\t}\n\n\t\t\ttailOutput += text;\n\t\t\tconst totalLines = completedLines + (hasOpenLine ? 1 : 0);\n\t\t\tif ((totalBytes > DEFAULT_MAX_BYTES || totalLines > DEFAULT_MAX_LINES) && !fullOutputRequested) {\n\t\t\t\tensureFullOutputFile(tailOutput);\n\t\t\t} else if (fullOutputRequested) {\n\t\t\t\tappendFullOutput(text);\n\t\t\t}\n\t\t\ttailOutput = trimToLastUtf8Bytes(tailOutput, maxOutputBytes, encoder);\n\t\t\toptions?.onChunk?.(text, createProgress);\n\t\t} catch (error) {\n\t\t\tcaptureError = toExecutionError(error);\n\t\t}\n\t};\n\n\ttry {\n\t\tconst result = await env.exec(command, {\n\t\t\tcwd: options?.cwd,\n\t\t\tenv: options?.env,\n\t\t\tinheritEnv: options?.inheritEnv,\n\t\t\ttimeout: options?.timeout,\n\t\t\tabortSignal: options?.abortSignal,\n\t\t\tonStdout: onChunk,\n\t\t\tonStderr: onChunk,\n\t\t});\n\t\tacceptingOutput = false;\n\t\tlet progress = createProgress();\n\t\tif (progress.truncation.truncated && !fullOutputRequested) ensureFullOutputFile(tailOutput);\n\t\tconst writeResult = await writeChain;\n\t\tif (!writeResult.ok) return err(writeResult.error);\n\t\tif (captureError) return err(captureError);\n\t\tprogress = createProgress();\n\n\t\tif (!result.ok) {\n\t\t\tif (result.error.code === \"aborted\" || options?.abortSignal?.aborted) {\n\t\t\t\treturn ok({\n\t\t\t\t\t...progress,\n\t\t\t\t\texitCode: undefined,\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\ttruncated: progress.truncation.truncated,\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (options?.returnExecutionErrors) {\n\t\t\t\treturn ok({\n\t\t\t\t\t...progress,\n\t\t\t\t\texitCode: undefined,\n\t\t\t\t\tcancelled: false,\n\t\t\t\t\ttruncated: progress.truncation.truncated,\n\t\t\t\t\texecutionError: result.error,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn err(result.error);\n\t\t}\n\t\tconst cancelled = options?.abortSignal?.aborted ?? false;\n\t\treturn ok({\n\t\t\t...progress,\n\t\t\texitCode: cancelled ? undefined : result.value.exitCode,\n\t\t\tcancelled,\n\t\t\ttruncated: progress.truncation.truncated,\n\t\t});\n\t} catch (error) {\n\t\tacceptingOutput = false;\n\t\treturn err(toExecutionError(error));\n\t}\n}\n"]}

package/dist/harness/utils/shell-output.js

@@ -0,0 +1,181 @@
+import { ExecutionError, err, ok, toError } from "../types.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "./truncate.js";
+function toExecutionError(error) {
+    if (error instanceof ExecutionError)
+        return error;
+    const cause = toError(error);
+    return new ExecutionError("unknown", cause.message, cause);
+}
+export function sanitizeBinaryOutput(str) {
+    return Array.from(str)
+        .filter((char) => {
+        const code = char.codePointAt(0);
+        if (code === undefined)
+            return false;
+        if (code === 0x09 || code === 0x0a || code === 0x0d)
+            return true;
+        if (code <= 0x1f)
+            return false;
+        if (code >= 0xfff9 && code <= 0xfffb)
+            return false;
+        return true;
+    })
+        .join("");
+}
+function trimToLastUtf8Bytes(text, maxBytes, encoder) {
+    const bytes = encoder.encode(text);
+    if (bytes.byteLength <= maxBytes)
+        return text;
+    let start = bytes.byteLength - maxBytes;
+    while (start < bytes.byteLength && ((bytes[start] ?? 0) & 0xc0) === 0x80)
+        start++;
+    return new TextDecoder().decode(bytes.subarray(start));
+}
+export async function executeShellWithCapture(env, command, options) {
+    let tailOutput = "";
+    const maxOutputBytes = DEFAULT_MAX_BYTES * 2;
+    const encoder = new TextEncoder();
+    let totalBytes = 0;
+    let completedLines = 0;
+    let hasOpenLine = false;
+    let currentLineBytes = 0;
+    let fullOutputPath;
+    let fullOutputRequested = false;
+    let acceptingOutput = true;
+    let writeChain = Promise.resolve(ok(undefined));
+    let captureError;
+    const appendFullOutput = (text) => {
+        if (!fullOutputRequested || captureError)
+            return;
+        writeChain = writeChain.then(async (previous) => {
+            if (!previous.ok)
+                return previous;
+            if (!fullOutputPath)
+                return err(new ExecutionError("unknown", "Full output path was not created"));
+            const appendResult = await env.appendFile(fullOutputPath, text);
+            return appendResult.ok ? ok(undefined) : err(toExecutionError(appendResult.error));
+        });
+    };
+    const ensureFullOutputFile = (initialContent) => {
+        if (fullOutputRequested || captureError)
+            return;
+        fullOutputRequested = true;
+        writeChain = writeChain.then(async (previous) => {
+            if (!previous.ok)
+                return previous;
+            const tempFile = await env.createTempFile({ prefix: "bash-", suffix: ".log" });
+            if (!tempFile.ok)
+                return err(toExecutionError(tempFile.error));
+            fullOutputPath = tempFile.value;
+            const appendResult = await env.appendFile(tempFile.value, initialContent);
+            return appendResult.ok ? ok(undefined) : err(toExecutionError(appendResult.error));
+        });
+    };
+    const createProgress = () => {
+        const tailTruncation = truncateTail(tailOutput);
+        const totalLines = completedLines + (hasOpenLine ? 1 : 0);
+        const truncated = totalLines > DEFAULT_MAX_LINES || totalBytes > DEFAULT_MAX_BYTES;
+        const truncation = {
+            ...tailTruncation,
+            truncated,
+            truncatedBy: truncated
+                ? (tailTruncation.truncatedBy ?? (totalBytes > DEFAULT_MAX_BYTES ? "bytes" : "lines"))
+                : null,
+            totalLines,
+            totalBytes,
+        };
+        return {
+            output: truncated ? truncation.content : tailOutput,
+            truncation,
+            fullOutputPath,
+            lastLineBytes: currentLineBytes,
+        };
+    };
+    const onChunk = (chunk) => {
+        if (!acceptingOutput)
+            return;
+        try {
+            const text = sanitizeBinaryOutput(chunk).replace(/\r/g, "");
+            const textBytes = encoder.encode(text).byteLength;
+            totalBytes += textBytes;
+            const newlineCount = text.split("\n").length - 1;
+            completedLines += newlineCount;
+            const lastNewline = text.lastIndexOf("\n");
+            if (lastNewline >= 0) {
+                const trailingText = text.slice(lastNewline + 1);
+                currentLineBytes = encoder.encode(trailingText).byteLength;
+                hasOpenLine = trailingText.length > 0;
+            }
+            else if (text.length > 0) {
+                currentLineBytes += textBytes;
+                hasOpenLine = true;
+            }
+            tailOutput += text;
+            const totalLines = completedLines + (hasOpenLine ? 1 : 0);
+            if ((totalBytes > DEFAULT_MAX_BYTES || totalLines > DEFAULT_MAX_LINES) && !fullOutputRequested) {
+                ensureFullOutputFile(tailOutput);
+            }
+            else if (fullOutputRequested) {
+                appendFullOutput(text);
+            }
+            tailOutput = trimToLastUtf8Bytes(tailOutput, maxOutputBytes, encoder);
+            options?.onChunk?.(text, createProgress);
+        }
+        catch (error) {
+            captureError = toExecutionError(error);
+        }
+    };
+    try {
+        const result = await env.exec(command, {
+            cwd: options?.cwd,
+            env: options?.env,
+            inheritEnv: options?.inheritEnv,
+            timeout: options?.timeout,
+            abortSignal: options?.abortSignal,
+            onStdout: onChunk,
+            onStderr: onChunk,
+        });
+        acceptingOutput = false;
+        let progress = createProgress();
+        if (progress.truncation.truncated && !fullOutputRequested)
+            ensureFullOutputFile(tailOutput);
+        const writeResult = await writeChain;
+        if (!writeResult.ok)
+            return err(writeResult.error);
+        if (captureError)
+            return err(captureError);
+        progress = createProgress();
+        if (!result.ok) {
+            if (result.error.code === "aborted" || options?.abortSignal?.aborted) {
+                return ok({
+                    ...progress,
+                    exitCode: undefined,
+                    cancelled: true,
+                    truncated: progress.truncation.truncated,
+                });
+            }
+            if (options?.returnExecutionErrors) {
+                return ok({
+                    ...progress,
+                    exitCode: undefined,
+                    cancelled: false,
+                    truncated: progress.truncation.truncated,
+                    executionError: result.error,
+                });
+            }
+            return err(result.error);
+        }
+        const cancelled = options?.abortSignal?.aborted ?? false;
+        return ok({
+            ...progress,
+            exitCode: cancelled ? undefined : result.value.exitCode,
+            cancelled,
+            truncated: progress.truncation.truncated,
+        });
+    }
+    catch (error) {
+        acceptingOutput = false;
+        return err(toExecutionError(error));
+    }
+}
+//# sourceMappingURL=shell-output.js.map