@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/tools/impl/index.d.ts

@@ -0,0 +1,37 @@
+import "./advisor.ts";
+import "./agent.ts";
+import "./ask-user-question.ts";
+import "./bash.ts";
+import "./cron.ts";
+import "./edit.ts";
+import "./enter-plan-mode.ts";
+import "./enter-worktree.ts";
+import "./exit-plan-mode.ts";
+import "./exit-worktree.ts";
+import "./glob.ts";
+import "./grep.ts";
+import "./monitor.ts";
+import "./notebook-edit.ts";
+import "./push-notification.ts";
+import "./read.ts";
+import "./report-findings.ts";
+import "./schedule-wakeup.ts";
+import "./task-graph.ts";
+import "./task-output.ts";
+import "./task-stop.ts";
+import "./todo-write.ts";
+import "./write.ts";
+import "./list-mcp-resources-tool.ts";
+import "./read-mcp-resource-tool.ts";
+import "./read-mcp-resource-dir-tool.ts";
+import "./refresh-mcp-tools.ts";
+import "./tool-search.ts";
+import "./wait-for-mcp-servers.ts";
+import "./send-message.ts";
+import "./list-agents.ts";
+import "./read-notifications.ts";
+import "./skill.ts";
+import "./workflow.ts";
+import "./web-fetch.ts";
+import "./web-search.ts";
+export declare const EXECUTORS_WIRED = true;

package/dist/tools/impl/list-agents.d.ts

@@ -0,0 +1,7 @@
+import "../descriptors/list-agents.ts";
+import "../descriptors/winter-list-agents.ts";
+import { type ToolExecutor } from "../registry.js";
+/** Read off the one definition, so the registered name and the descriptor's can never disagree. */
+export declare const LIST_AGENTS_TOOL_NAME: string;
+export declare const listAgentsExecutor: ToolExecutor;
+export declare const WINTER_CANONICAL_LIST_AGENTS_TOOL_NAME: string;

package/dist/tools/impl/list-mcp-resources-tool.d.ts

@@ -0,0 +1,9 @@
+import "../descriptors/list-mcp-resources-tool.ts";
+import { type ToolExecutionContext, type ToolExecutor } from "../registry.js";
+import type { McpLifecycle } from "../../mcp/lifecycle.js";
+export declare const LIST_MCP_RESOURCES_TOOL_NAME = "ListMcpResourcesTool";
+export type McpLifecycleResolver = (ctx: ToolExecutionContext) => McpLifecycle | undefined;
+export interface ListMcpResourcesDeps {
+    resolveLifecycle: McpLifecycleResolver;
+}
+export declare function createListMcpResourcesExecutor(deps: ListMcpResourcesDeps): ToolExecutor;

package/dist/tools/impl/monitor.d.ts

@@ -0,0 +1,66 @@
+import { isDisallowedAddress } from "@yanlinglabs/winter-provider-runtime";
+import "../descriptors/monitor.ts";
+import { type ToolExecutor, type ToolExecutionContext, type ToolResultPayload } from "../registry.js";
+import { type SandboxBrand } from "../../sandbox/profile.js";
+import { type GlobDenyEntry } from "../../permissions/file-rules.js";
+interface MonitorInput {
+    description: string;
+    timeout_ms: number;
+    persistent: boolean;
+    command?: string;
+    ws?: {
+        url: string;
+        protocols?: string[];
+    };
+}
+declare function parseMonitorInput(input: unknown): MonitorInput | {
+    error: string;
+};
+declare function buildMonitorRunCommandOptions(ctx: ToolExecutionContext): {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    settings: typeof ctx.sandboxSettings;
+    writableRoots: string[];
+    denyWritePaths?: string[];
+    denyReadPaths?: string[];
+    /** Fix round 11: glob-shaped denyWrite/denyRead entries, pre-converted to SBPL regex source -- see `splitDenyPathsByGlobShape`'s own header. */
+    denyWriteRegexes?: string[];
+    denyReadRegexes?: string[];
+    /** Fix round 12: each glob-shaped denyWrite/denyRead entry's own canonicalized fixed-prefix directory -- feeds the ancestor-rename-bypass fix. */
+    denyWriteGlobFixedPrefixes?: string[];
+    denyReadGlobFixedPrefixes?: string[];
+    /** Fix round 13: each glob-shaped denyRead entry, its regex PAIRED with its own fixed prefix -- feeds the read-deny-keep-in-place fix. */
+    denyReadGlobEntries?: GlobDenyEntry[];
+    home: string;
+    /** Phase 5 fix wave, I1: the resolved winter root, distinct from the OS home above. */
+    winterHome?: string;
+    /** P7a (D19): the session's brand -- the dot-dir names the seatbelt fences. */
+    brand?: SandboxBrand;
+    /** Fix round 16, item 2: `sandbox.filesystem.allowGitConfig` -- see `SandboxFilesystemSettings.allowGitConfig`'s own header. */
+    allowGitConfigWrites?: boolean;
+    /**
+     * Phase 6 Task 3 (R6-6, P4 carry): the engine's per-turn abort, threaded to `runCommand`'s
+     * already-existing process-group kill. Monitor's command half shares Bash's spawn mechanism, so it
+     * shares this obligation -- "a stopped child starts nothing new AND its in-flight command is
+     * killed" is not satisfied by covering only one of the two tools that spawn one.
+     *
+     * NOT PASSED TO `runCommand` (review r1 finding 2, controller ruling): a Monitor is a background
+     * task, and the pin's backgrounded shell drops its abort listeners -- a turn interrupt must not end
+     * it. `runMonitorCommand` strips this field; the session teardown (`stopSessionShellTasks`) and
+     * TaskStop are its kill doors. Kept on the options shape so the one builder stays comparable with
+     * bash.ts's own.
+     */
+    signal?: AbortSignal;
+};
+type WsValidation = {
+    ok: true;
+    connectUrl: URL;
+    hostHeader: string;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function validateWsEndpoint(rawUrl: string): Promise<WsValidation>;
+export declare function connectMonitorWs(url: string, protocols: string[] | undefined, description: string, timeoutMs: number, persistent: boolean, ctx: ToolExecutionContext, hostHeader?: string): Promise<ToolResultPayload>;
+export declare const monitorExecutor: ToolExecutor;
+export { parseMonitorInput, isDisallowedAddress, validateWsEndpoint, buildMonitorRunCommandOptions };

package/dist/tools/impl/notebook-edit.d.ts

@@ -0,0 +1 @@
+import "../descriptors/index.ts";

package/dist/tools/impl/push-notification.d.ts

@@ -0,0 +1,4 @@
+import "../descriptors/index.ts";
+export type PushNotifier = (message: string) => void;
+export declare function configurePushNotifier(notifier: PushNotifier): void;
+export declare function resetPushNotifierForTest(): void;

package/dist/tools/impl/read-ladder.d.ts

@@ -0,0 +1,25 @@
+import type { SessionReadState } from "../read-state.js";
+import type { ReadAccessProbe } from "../../permissions/evaluator.js";
+export type ReadLadderProfile = "strict" | "relaxed";
+export declare const DEFAULT_READ_LADDER_PROFILE: ReadLadderProfile;
+export type ReadLadderOperation = "edit" | "overwrite";
+export interface ReadLadderInput {
+    filePath: string;
+    currentMtimeMs: number;
+    operation: ReadLadderOperation;
+    hasUnambiguousCurrentMatch?: boolean;
+    profile?: ReadLadderProfile;
+}
+export interface ReadLadderDeps {
+    readState: SessionReadState;
+    probeReadAccess: (filePath: string) => ReadAccessProbe;
+}
+export type ReadLadderDecision = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: string;
+};
+export declare function evaluateReadLadder(input: ReadLadderInput, deps: ReadLadderDeps): ReadLadderDecision;
+export type PostOperationReadKind = "full" | "carryForward";
+export declare function recordPostOperationRead(deps: ReadLadderDeps, filePath: string, kind: PostOperationReadKind, mtimeMs: number): void;

package/dist/tools/impl/read-mcp-resource-dir-tool.d.ts

@@ -0,0 +1,9 @@
+import "../descriptors/read-mcp-resource-dir-tool.ts";
+import { type ToolExecutor } from "../registry.js";
+import type { McpLifecycleResolver } from "./list-mcp-resources-tool.js";
+export declare const READ_MCP_RESOURCE_DIR_TOOL_NAME = "ReadMcpResourceDirTool";
+export interface ReadMcpResourceDirDeps {
+    resolveLifecycle: McpLifecycleResolver;
+}
+export declare function isDirectChildUri(parent: string, candidate: string): boolean;
+export declare function createReadMcpResourceDirExecutor(deps: ReadMcpResourceDirDeps): ToolExecutor;

package/dist/tools/impl/read-mcp-resource-tool.d.ts

@@ -0,0 +1,9 @@
+import "../descriptors/read-mcp-resource-tool.ts";
+import { type ToolExecutor } from "../registry.js";
+import type { McpLifecycleResolver } from "./list-mcp-resources-tool.js";
+export declare const READ_MCP_RESOURCE_TOOL_NAME = "ReadMcpResourceTool";
+export interface ReadMcpResourceDeps {
+    resolveLifecycle: McpLifecycleResolver;
+}
+export declare function saveBlobToTempDir(tempDir: string, blobBase64: string, mimeType: string | undefined): string;
+export declare function createReadMcpResourceExecutor(deps: ReadMcpResourceDeps): ToolExecutor;

package/dist/tools/impl/read-notifications.d.ts

@@ -0,0 +1,5 @@
+import "../descriptors/read-notifications.ts";
+import { type ToolExecutor } from "../registry.js";
+/** Read off the one definition, so the registered name and the descriptor's can never disagree. */
+export declare const READ_NOTIFICATIONS_TOOL_NAME: string;
+export declare const readNotificationsExecutor: ToolExecutor;

package/dist/tools/impl/read.d.ts

@@ -0,0 +1,44 @@
+import "../descriptors/index.ts";
+export type ReadBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    media_type: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    data?: string;
+    note?: string;
+} | {
+    type: "pdf";
+    media_type: "application/pdf";
+    bytes: number;
+    totalPages?: number;
+    requestedPages?: {
+        start: number;
+        end: number;
+    };
+    data?: string;
+    note: string;
+};
+export interface ReadBlocksEnvelope {
+    winterReadBlocks: ReadBlock[];
+}
+export declare function parsePngDimensions(buf: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+export declare function parseGifDimensions(buf: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+export declare function parseBmpDimensions(buf: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+export declare function parseJpegDimensions(buf: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+export declare function countPdfPages(bytes: Buffer): number | undefined;

package/dist/tools/impl/refresh-mcp-tools.d.ts

@@ -0,0 +1,8 @@
+import "../descriptors/refresh-mcp-tools.ts";
+import { type ToolExecutor } from "../registry.js";
+import type { McpLifecycleResolver } from "./list-mcp-resources-tool.js";
+export declare const REFRESH_MCP_TOOLS_NAME = "RefreshMcpTools";
+export interface RefreshMcpToolsDeps {
+    resolveLifecycle: McpLifecycleResolver;
+}
+export declare function createRefreshMcpToolsExecutor(deps: RefreshMcpToolsDeps): ToolExecutor;

package/dist/tools/impl/report-findings.d.ts

@@ -0,0 +1 @@
+import "../descriptors/index.ts";

package/dist/tools/impl/schedule-wakeup.d.ts

@@ -0,0 +1,2 @@
+import "../descriptors/index.ts";
+export declare function resetScheduleWakeupStoreForTest(sessionId?: string): void;

package/dist/tools/impl/send-message.d.ts

@@ -0,0 +1,7 @@
+import "../descriptors/send-message.ts";
+import "../descriptors/winter-send-message.ts";
+import { type ToolExecutor } from "../registry.js";
+/** Read off the one definition, so the registered name and the descriptor's can never disagree. */
+export declare const SEND_MESSAGE_TOOL_NAME: string;
+export declare const sendMessageExecutor: ToolExecutor;
+export declare const WINTER_CANONICAL_SEND_MESSAGE_TOOL_NAME: string;

package/dist/tools/impl/skill.d.ts

@@ -0,0 +1,5 @@
+import "../descriptors/skill.ts";
+import { type ToolExecutor } from "../registry.js";
+import { SKILL_TOOL_NAME } from "../../skills/option.js";
+export { SKILL_TOOL_NAME };
+export declare const skillExecutor: ToolExecutor;

package/dist/tools/impl/task-graph.d.ts

@@ -0,0 +1 @@
+import "../descriptors/index.ts";

package/dist/tools/impl/task-output.d.ts

@@ -0,0 +1,16 @@
+import "../descriptors/task-output.ts";
+import { type ToolExecutor } from "../registry.js";
+interface TaskOutputInput {
+    task_id: string;
+    block: boolean;
+    timeout: number;
+}
+declare function parseTaskOutputInput(input: unknown): TaskOutputInput | {
+    error: string;
+};
+declare function resolveClampedTimeout(requested: number): {
+    effective: number;
+    wasClamped: boolean;
+};
+declare const taskOutputExecutor: ToolExecutor;
+export { parseTaskOutputInput, taskOutputExecutor, resolveClampedTimeout };

package/dist/tools/impl/task-stop.d.ts

@@ -0,0 +1,11 @@
+import "../descriptors/task-stop.ts";
+import { type ToolExecutor } from "../registry.js";
+interface TaskStopInput {
+    task_id?: string;
+    shell_id?: string;
+}
+declare function parseTaskStopInput(input: unknown): TaskStopInput | {
+    error: string;
+};
+declare const taskStopExecutor: ToolExecutor;
+export { parseTaskStopInput, taskStopExecutor };

package/dist/tools/impl/todo-write.d.ts

@@ -0,0 +1,8 @@
+import "../descriptors/index.ts";
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export interface Todo {
+    content: string;
+    status: TodoStatus;
+    activeForm: string;
+}
+export declare function resetTodoStoreForTest(sessionId?: string): void;

package/dist/tools/impl/tool-search.d.ts

@@ -0,0 +1,4 @@
+import "../descriptors/tool-search.ts";
+import { type ToolExecutor } from "../registry.js";
+export declare const TOOL_SEARCH_TOOL_NAME = "ToolSearch";
+export declare const toolSearchExecutor: ToolExecutor;

package/dist/tools/impl/wait-for-mcp-servers.d.ts

@@ -0,0 +1,29 @@
+import "../descriptors/wait-for-mcp-servers.ts";
+import { type ToolExecutor } from "../registry.js";
+import type { McpServerStateSource } from "../../mcp/state.js";
+export declare const WAIT_FOR_MCP_SERVERS_TOOL_NAME = "WaitForMcpServers";
+export interface WaitForMcpServersResult {
+    ready: boolean;
+    connected: string[];
+    cached?: string[];
+    failed: string[];
+    stillPending: string[];
+    needsAuth: string[];
+    disabled: string[];
+    unconfigured?: string[];
+    replRouted?: boolean;
+    unknown: string[];
+}
+export type WaitForMcpServersOutcome = {
+    ok: true;
+    result: WaitForMcpServersResult;
+} | {
+    ok: false;
+    message: string;
+};
+export interface WaitForMcpServersDeps {
+    stateSource?: McpServerStateSource;
+    pendingWaitMs?: number;
+}
+export declare function executeWaitForMcpServers(input: unknown, deps: WaitForMcpServersDeps): Promise<WaitForMcpServersOutcome>;
+export declare const waitForMcpServersExecutor: ToolExecutor;

package/dist/tools/impl/web-fetch.d.ts

@@ -0,0 +1,36 @@
+import "../descriptors/web-fetch.ts";
+import { type ToolExecutionContext, type ToolExecutor } from "../registry.js";
+import { WebFetchCache } from "./_web-fetch-cache.js";
+import { type WebFetchNetDeps } from "./_web-fetch-net.js";
+declare const PERMISSIVE_GUIDELINES = "Provide a concise response based on the content above. Include relevant details, code examples, and documentation excerpts as needed.";
+declare const STRICT_GUIDELINES = "Provide a concise response based only on the content above. In your response:\n - Enforce a strict 125-character maximum for quotes from any source document. Open Source Software is ok as long as we respect the license.\n - Use quotation marks for exact language from articles; any language outside of the quotation should never be word-for-word the same.\n - You are not a lawyer and never comment on the legality of your own prompts and responses.\n - Never produce or reproduce exact song lyrics.";
+declare const BINARY_SAVE_BUDGET_BYTES: number;
+/**
+ * Forgets `sessionId`'s spend (whole-branch review MINOR 4). Called from the ROOT run's own teardown in
+ * `engine.ts`, beside the search client's close and the fetch cache's own `forgetSession`: nothing used
+ * to remove a row, so on the in-process `query()` path the map grew forever AND an in-process
+ * `--resume` of the same id inherited the previous run's spend. A resumed run starts fresh, which is
+ * what a resumed session gets in claude (a new process).
+ */
+export declare function forgetWebFetchBinarySaveBudgetForSession(sessionId: string): void;
+/**
+ * `saveBinaryToTemp`'s "the session's saved-binary allowance is used up" answer. RENAMED away from the
+ * bare `"budget-exceeded"` it used to be (whole-branch review, NIT): that string is also the VALUE of
+ * `INNER_MODEL_BUDGET_EXCEEDED_DETAIL`, an unrelated fact (the session's spend ceiling stopping an
+ * inner model pass) that this same file matches on. Nothing conflated them today; two identical
+ * literals a few hundred lines apart is how something eventually would.
+ */
+export declare const BINARY_SAVE_BUDGET_EXCEEDED = "binary-save-budget-exceeded";
+declare function saveBinaryToTemp(ctx: ToolExecutionContext, url: URL, bytes: Uint8Array): Promise<string | undefined | typeof BINARY_SAVE_BUDGET_EXCEEDED>;
+/** The digest pass was stopped because the session reached its spending limit -- NOT an interruption, and retrying cannot help. */
+export declare const WEB_FETCH_BUDGET_STOP_MESSAGE = "WebFetch fetched the page but could not digest it: this session has reached its spending limit, so no further model calls can be made. Retrying will not help -- continue with the information already gathered, or ask the user to raise the session's budget.";
+export interface WebFetchExecutorDeps {
+    net?: WebFetchNetDeps;
+    cache?: WebFetchCache;
+    resolveHost?: (hostname: string) => Promise<readonly string[]>;
+    now?: () => number;
+}
+export declare function createWebFetchExecutor(deps?: WebFetchExecutorDeps): ToolExecutor;
+export { PERMISSIVE_GUIDELINES, STRICT_GUIDELINES };
+export declare const WEB_FETCH_DEFAULT_TIMEOUT_MS = 60000;
+export { saveBinaryToTemp, BINARY_SAVE_BUDGET_BYTES };

package/dist/tools/impl/web-search.d.ts

@@ -0,0 +1,30 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { type ToolExecutor } from "../registry.js";
+import { type ExaBackendState, type ExaSearchClientOptions } from "./_exa-client.js";
+type EnvBrand = Pick<BrandProfile, "envPrefix">;
+/** claude's own cap (research file, "maxResultSizeChars: 100000"). No per-tool cap seam exists on this registry (verified: no `maxResultChars`/`maxResultSizeChars` anywhere in it), so the executor enforces it itself. */
+export declare const WEB_SEARCH_RESULT_CAP = 100000;
+export interface WebSearchInput {
+    query: string;
+    allowed_domains?: string[];
+    blocked_domains?: string[];
+}
+/**
+ * The most entries either domain list may carry. claude has no analogue -- its schema-validated
+ * `string[]` is forwarded whole, and the extraction notes record no bound -- but a list is a MODEL-
+ * supplied array that this runtime hands to a third-party backend, and a 100,000-element one was
+ * forwarded verbatim (whole-branch review MINOR 10). A thousand is far past any real filter and small
+ * enough that no request built from it is absurd.
+ */
+export declare const MAX_DOMAIN_LIST_ENTRIES = 1000;
+export interface WebSearchExecutorDeps {
+    /** Forwarded into `createExaSearchClient` for the session's first call. Tests set `endpoint`/`state`/`sleep`/`connect`. */
+    exaClientOptions?: Pick<ExaSearchClientOptions, "endpoint" | "state" | "sleep" | "connect" | "callTimeoutMs" | "connectTimeoutMs" | "maxResultChars">;
+    /** The SAME breaker state object passed above (defaults to the process-wide one, matching `_exa-client.ts`'s own default) -- read here too, to decide the per-call cap BEFORE the loop starts. */
+    backendState?: ExaBackendState;
+    now?: () => number;
+    brand?: EnvBrand;
+    resultCap?: number;
+}
+export declare function createWebSearchExecutor(deps?: WebSearchExecutorDeps): ToolExecutor;
+export {};

package/dist/tools/impl/workflow.d.ts

@@ -0,0 +1,5 @@
+import "../descriptors/workflow.ts";
+import { type WorkflowRuntimeDeps } from "../../workflows/runtime.js";
+export declare const WORKFLOW_TOOL_NAME = "Workflow";
+/** Test-only, mirroring every sibling singleton's own escape hatch (bun shares one module instance across a `bun test` run). */
+export declare function resetWorkflowToolForTest(overrides?: Partial<WorkflowRuntimeDeps>): void;

package/dist/tools/impl/write.d.ts

@@ -0,0 +1,8 @@
+import "../descriptors/index.ts";
+export interface DiffLine {
+    type: "context" | "add" | "remove";
+    oldLineNumber?: number;
+    newLineNumber?: number;
+    content: string;
+}
+export declare function computeLineDiff(oldText: string, newText: string): DiffLine[];

package/dist/tools/paths-seam.d.ts

@@ -0,0 +1,6 @@
+import type { RegisteredTool } from "./registry.js";
+export type ExtractPaths = NonNullable<RegisteredTool["extractPaths"]>;
+export type ExtractedPaths = ReturnType<ExtractPaths>;
+export declare function resolveCandidatePaths(candidates: readonly string[], baseDir: string): string[];
+export declare function mergePathSets(a: ExtractedPaths, b: ExtractedPaths): ExtractedPaths;
+export declare function emptyPathSet(): ExtractedPaths;

package/dist/tools/read-state.d.ts

@@ -0,0 +1,12 @@
+export interface ReadRecord {
+    complete: boolean;
+    mtimeMs: number;
+}
+export interface SessionReadState {
+    recordRead(p: string, o: ReadRecord): void;
+    lookup(p: string): ReadRecord | undefined;
+}
+export interface SessionReadStateOptions {
+    cwd: string;
+}
+export declare function createSessionReadState(opts: SessionReadStateOptions): SessionReadState;