@a5c-ai/agent-core 5.0.1-staging.9f7009ce → 5.0.1-staging.a2865ee1a2da

package/README.md

@@ -5,16 +5,16 @@ Built-in programmatic session wrapper and agentic tool surface for Babysitter ru
 <!-- docs-status:start -->
 > Status: Public advanced/runtime package.
 > Canonical docs home: [Package and Plugin Docs Map](../../docs/package-and-plugin-map.md).
-> This README defines the package contract for runtime consumers and published dependents such as `@a5c-ai/babysitter-agent`.
+> This README defines the package contract for runtime consumers and published dependents such as `@a5c-ai/agent-platform`.
 <!-- docs-status:end -->
 
 ## Package role
 
-`@a5c-ai/agent-core` sits between `@a5c-ai/babysitter-agent`, `@a5c-ai/agent-mux`, and `@a5c-ai/babysitter-sdk`:
+`@a5c-ai/agent-core` sits between `@a5c-ai/agent-platform`, `@a5c-ai/agent-mux`, and `@a5c-ai/babysitter-sdk`:
 
 - `createAgentCoreSession()` wraps an `@a5c-ai/agent-mux` client for in-process prompt execution.
 - `createAgentCoreToolDefinitions()` assembles the built-in Babysitter-flavored tool surface that host runtimes can inject into planning, resume, or delegated-task flows.
-- `@a5c-ai/babysitter-agent` re-exports these APIs from `src/harness/index.ts`, uses `createAgentCoreSession()` for direct `agent-core` harness invocation in `src/harness/invoker.ts`, and injects tool definitions into plan-process and resume-run flows.
+- `@a5c-ai/agent-platform` re-exports these APIs from `src/harness/index.ts`, uses `createAgentCoreSession()` for direct `agent-core` harness invocation in `src/harness/invoker.ts`, and injects tool definitions into plan-process and resume-run flows.
 - `@a5c-ai/babysitter-sdk` still owns run directories, journals, task/effect lifecycle, and config defaults. `agent-core` does not replace the SDK orchestration layer.
 
 This package is published as a runtime dependency surface for higher-level Babysitter runtimes. It is still an advanced/operator-facing building block rather than the primary entrypoint for new users.
@@ -37,9 +37,18 @@ import {
   resetRunScopedConfig,
   stripHtmlTags,
   type AgentCoreEventListener,
+  type AgentCoreImageBase64PromptPart,
+  type AgentCoreImageUrlPromptPart,
+  type AgentCoreJsonSchema,
+  type AgentCoreOutputFormat,
+  type AgentCorePromptInput,
+  type AgentCorePromptOptions,
+  type AgentCorePromptPart,
   type AgentCorePromptResult,
   type AgentCoreSessionEvent,
   type AgentCoreSessionOptions,
+  type AgentCoreStructuredOutputOptions,
+  type AgentCoreTextPromptPart,
   type AgentCoreToolOptions,
   type CustomToolDefinition,
   type ToolResult,
@@ -64,8 +73,11 @@ Core handle methods:
 
 - `initialize()`: currently a no-op placeholder for compatibility.
 - `prompt(text, timeout?)`: starts a run, streams events to subscribers, and returns `{ output, duration, success, exitCode }`.
+- `prompt(input, options?)`: accepts text or multimodal prompt parts and optional structured-output settings.
 - `steer(text)`: sends immediate steering text while a prompt is active, or queues it for the next prompt.
 - `followUp(text)`: queues a post-response follow-up when streaming, or appends it to the next prompt when idle.
+- `getHistory()`: returns a defensive copy of persisted user/assistant turns for the session handle.
+- `clearHistory()`: clears persisted user/assistant turns without changing listeners, options, or the current session id.
 - `subscribe(listener)`: receives normalized `AgentCoreSessionEvent` payloads, including `session_start`.
 - `abort()`: aborts the active run if one is in progress.
 - `dispose()`: aborts the active run, clears listeners, and drops queued follow-ups.
@@ -75,6 +87,8 @@ Core handle methods:
 Session behavior that matters to host integrations:
 
 - Agent-core reuses the `sessionId` learned from prior runs, so later prompts continue the same agent-mux session when the backend supports it.
+- Agent-core also keeps successful user/assistant turns on the session handle and includes bounded prior history in later direct provider prompts. System prompts are rebuilt from options for each request and are not stored in mutable history.
+- Failed prompts, timed-out requests, aborted requests, and malformed streams do not append partial assistant output to history.
 - Concurrent `prompt()` calls on the same handle are rejected.
 - Event payloads are normalized before subscribers see them. Non-object payloads become `{ type: "unknown", value }`.
 - Approval mode is `prompt` only when `uiContext` is present; otherwise agent-core uses `yolo`.
@@ -86,11 +100,71 @@ Session behavior that matters to host integrations:
 | `workspace` | Forwarded to agent-mux as `cwd`. |
 | `model` | Forwarded to agent-mux as `model`. |
 | `timeout` | Forwarded to agent-mux as `timeout`. |
+| `maxHistoryTurns` | Maximum persisted user/assistant history entries retained on the session handle. Defaults to 20. |
+| `maxHistoryTokens` | Maximum estimated tokens from prior history sent with a prompt. Uses the package's provider/model-aware rough token estimator and drops oldest entries first. |
 | `thinkingLevel` | Translated to agent-mux `thinkingEffort` (`minimal`/`low` -> `low`, `medium` -> `medium`, `high` -> `high`, `xhigh` -> `max`). |
 | `systemPrompt` | Used as the base `systemPrompt`. |
 | `appendSystemPrompt` | Appended to the final `systemPrompt` before dispatch. |
 | `uiContext` | Switches run approval mode to `prompt`; when omitted, agent-core uses `yolo`. |
 | `backend` | Selects the agent-mux adapter/backend forwarded as `agent`. |
+| `outputFormat` | Optional structured-output mode: `text`, `json_object`, or `json_schema`. |
+| `outputSchema` | JSON Schema used when `outputFormat` is `json_schema`. |
+| `outputSchemaName` | Provider-visible schema name. Defaults to `agent_core_response`. |
+| `outputSchemaStrict` | Provider strictness flag for schema-capable APIs. Defaults to `true` for `json_schema`. |
+
+### Structured Output
+
+Structured output is opt-in. Plain `prompt(text, timeout?)` remains the default and returns only the text output fields used by existing callers.
+
+```ts
+const session = createAgentCoreSession({
+  model: "gpt-5.5",
+  outputFormat: "json_schema",
+  outputSchemaName: "answer_payload",
+  outputSchema: {
+    type: "object",
+    required: ["answer"],
+    properties: {
+      answer: { type: "string" },
+    },
+  },
+});
+
+const result = await session.prompt<{ answer: string }>("Answer as JSON");
+if (result.success) {
+  console.log(result.parsed?.answer);
+} else {
+  console.error(result.validationError ?? result.output);
+}
+```
+
+OpenAI-compatible and Azure endpoints receive `response_format` with either `{ type: "json_object" }` or a `json_schema` payload. Anthropic does not expose the same response-format field through this direct Messages API path, so agent-core injects a system instruction that requires JSON-only output and still parses/validates the returned text locally.
+
+`json_object` requires the model to return a JSON object. `json_schema` requires `outputSchema` and validates the parsed object for common JSON Schema constraints used by this package contract (`type`, `required`, `properties`, `items`, and `enum`). Parse or schema failures return `success: false`, `exitCode: 1`, the raw `output`, and `validationError`.
+
+Prompt-level options can override session defaults:
+
+```ts
+const result = await session.prompt<{ ok: boolean }>("Return status", {
+  outputFormat: "json_object",
+});
+```
+
+### Multimodal Input
+
+`prompt()` accepts an array of prompt parts for text plus image URL/base64 input:
+
+```ts
+await session.prompt([
+  { type: "text", text: "Describe the relevant details in these images." },
+  { type: "image_url", imageUrl: "https://example.com/screenshot.png" },
+  { type: "image_base64", mediaType: "image/png", data: rawBase64Png },
+]);
+```
+
+OpenAI-compatible and Azure endpoints receive Chat Completions content parts using `text` and `image_url`. Base64 images are converted to `data:<mediaType>;base64,...` URLs for those providers. Anthropic receives Messages API content blocks with `image` sources using either `url` or `base64`.
+
+Agent-core validates image URLs before dispatch (`http`/`https` only), requires `image/*` media types for base64 images, rejects data URLs in the base64 field, and caps raw base64 image payloads at 20 MiB. Image-bearing `ToolResult` support remains owned by #588; this API only covers direct session prompt input.
 
 ### Deprecated compatibility fields
 
@@ -98,7 +172,7 @@ These fields remain on `AgentCoreSessionOptions` for compatibility, but the curr
 
 | Option | Status | Migration note |
 | --- | --- | --- |
-| `toolsMode` | Deprecated, ignored by agent-core | Use backend-native configuration, or the PI wrapper in `@a5c-ai/babysitter-agent`, if you still need tool-surface control. |
+| `toolsMode` | Deprecated, ignored by agent-core | Use backend-native configuration, or the PI wrapper in `@a5c-ai/agent-platform`, if you still need tool-surface control. |
 | `customTools` | Deprecated, ignored by agent-core | Register host-side tools with `createAgentCoreToolDefinitions()` or use the PI wrapper for runtime custom-tool injection. |
 | `isolated` | Deprecated, ignored by agent-core | Use the PI wrapper if you still need extension/skills isolation controls. |
 | `ephemeral` | Deprecated, ignored by agent-core | Session persistence is determined by the selected agent-mux backend. |
@@ -106,7 +180,7 @@ These fields remain on `AgentCoreSessionOptions` for compatibility, but the curr
 | `enableCompaction` | Deprecated, ignored by agent-core | Compaction behavior belongs to the selected backend/runtime. |
 | `agentDir` | Deprecated, ignored by agent-core | Configure agent directories through the target backend instead. |
 
-If you still need the PI-era controls above, use the PI wrapper exposed from `@a5c-ai/babysitter-agent` rather than `@a5c-ai/agent-core`.
+If you still need the PI-era controls above, use the PI wrapper exposed from `@a5c-ai/agent-platform` rather than `@a5c-ai/agent-core`.
 
 ## Tool-definition API
 
@@ -118,6 +192,9 @@ If you still need the PI-era controls above, use the PI wrapper exposed from `@a
 - delegation tools: `AskUserQuestion`, `task`, `skill`
 - code tools: `calc`, `ast_grep`, `ast_edit`, `render_mermaid`, `notebook`
 - background/discovery/web tools: `background_status`, `background_list`, `tool_search`, `tool_fetch`, `web_search`, `fetch_process`
+- optional programmatic tool calling: `code_executor` when `programmaticToolCalling` is enabled
+
+The `calc` tool evaluates a constrained arithmetic language only: numeric literals, parentheses, unary `+`/`-`, and `+`, `-`, `*`, `/`, `%`, and `**`. It rejects identifiers, function calls, property access, assignment, malformed expressions, overlong input, and non-finite results. It does not use `eval`, `Function`, shell execution, or external processes.
 
 `AgentCoreToolOptions` controls how those definitions are wired into a host runtime:
 
@@ -127,6 +204,18 @@ If you still need the PI-era controls above, use the PI wrapper exposed from `@a
 - `onToolUse`: observer callback fired after tool wrapping.
 - `onBackgroundComplete`, `maxBackgroundProcesses`, `backgroundRegistry`: background-process lifecycle hooks and limits.
 - `deferredToolRegistry`: enables `tool_search` and `tool_fetch`.
+- `programmaticToolCalling`: opt-in Code Mode / Programmatic Tool Calling surface. When enabled, `code_executor` runs a bounded JavaScript async body with `tools.<name>(params)` and `callTool(name, params)` helpers for batching existing agent-core tools behind one model-level tool call.
+
+Example:
+
+```ts
+const tools = createAgentCoreToolDefinitions({
+  workspace: process.cwd(),
+  interactive: false,
+  deferredToolRegistry,
+  programmaticToolCalling: { maxToolCalls: 10, timeout: 60_000 },
+});
+```
 
 ### Interactive and cancellation contract
 
@@ -179,7 +268,7 @@ Source disambiguation uses `(source, sourceQualifier, name)`, so duplicate tool
 
 Current downstream integration boundaries in this repo:
 
-- `@a5c-ai/babysitter-agent`
+- `@a5c-ai/agent-platform`
   - re-exports the session/tool APIs from `src/harness/index.ts`
   - uses `createAgentCoreSession()` for the direct `agent-core` harness path in `src/harness/invoker.ts`
   - injects `createAgentCoreToolDefinitions()` into plan-process and delegated-task flows in `src/harness/internal/createRun/planProcess/*`
@@ -189,7 +278,7 @@ Current downstream integration boundaries in this repo:
 - `@a5c-ai/babysitter-sdk`
   - provides config defaults/env wiring used by the `config` tool and remains the owner of orchestration/run-state semantics outside this package
 
-In practice, use `agent-core` when you need an in-process runtime wrapper or bundled tool surface. Use `babysitter-agent` when you need the higher-level harness CLI/runtime entrypoints.
+In practice, use `agent-core` when you need an in-process runtime wrapper or bundled tool surface. Use `agent-platform` when you need the higher-level harness CLI/runtime entrypoints.
 
 ## Build, test, and CI
 

package/dist/agenticTools/background/state.d.ts

@@ -1,5 +1,7 @@
-import { BackgroundProcessRegistry } from "../../backgroundProcessRegistry";
-import type { AgenticToolOptions } from "../types";
-export declare function getBackgroundRegistry(options: AgenticToolOptions): BackgroundProcessRegistry;
-export declare function disposeBackgroundRegistry(options: AgenticToolOptions): void;
+/**
+ * Backwards-compatibility shim -- the canonical implementation now lives in
+ * `@a5c-ai/agent-runtime`.  This re-export keeps internal agent-core consumers
+ * working without changes.
+ */
+export { getBackgroundRegistry, disposeBackgroundRegistry, } from "@a5c-ai/agent-runtime";
 //# sourceMappingURL=state.d.ts.map

package/dist/agenticTools/background/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/background/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAInD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,yBAAyB,CAW5F;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAO3E"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/background/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC"}

package/dist/agenticTools/background/state.js

@@ -1,25 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBackgroundRegistry = getBackgroundRegistry;
-exports.disposeBackgroundRegistry = disposeBackgroundRegistry;
-const backgroundProcessRegistry_1 = require("../../backgroundProcessRegistry");
-const scopedRegistries = new WeakMap();
-function getBackgroundRegistry(options) {
-    if (options.backgroundRegistry) {
-        return options.backgroundRegistry;
-    }
-    let registry = scopedRegistries.get(options);
-    if (!registry) {
-        registry = new backgroundProcessRegistry_1.BackgroundProcessRegistry({ maxConcurrent: options.maxBackgroundProcesses });
-        scopedRegistries.set(options, registry);
-    }
-    return registry;
-}
-function disposeBackgroundRegistry(options) {
-    const registry = scopedRegistries.get(options);
-    if (!registry) {
-        return;
-    }
-    registry.dispose();
-    scopedRegistries.delete(options);
-}
+exports.disposeBackgroundRegistry = exports.getBackgroundRegistry = void 0;
+/**
+ * Backwards-compatibility shim -- the canonical implementation now lives in
+ * `@a5c-ai/agent-runtime`.  This re-export keeps internal agent-core consumers
+ * working without changes.
+ */
+var agent_runtime_1 = require("@a5c-ai/agent-runtime");
+Object.defineProperty(exports, "getBackgroundRegistry", { enumerable: true, get: function () { return agent_runtime_1.getBackgroundRegistry; } });
+Object.defineProperty(exports, "disposeBackgroundRegistry", { enumerable: true, get: function () { return agent_runtime_1.disposeBackgroundRegistry; } });

package/dist/agenticTools/browser/tool.js

@@ -25,8 +25,8 @@ function createBrowserTool() {
                 // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-assignment
                 puppeteer = await new Function("id", "return import(id)")("puppeteer");
             }
-            catch {
-                return (0, results_1.errorResult)("puppeteer is not installed. Install it with: npm install puppeteer");
+            catch (error) {
+                return (0, results_1.errorResult)(`puppeteer import failed: ${error instanceof Error ? error.message : String(error)}. Install with: npm install puppeteer`);
             }
             if (!browserInstance) {
                 browserInstance = await puppeteer.launch({

package/dist/agenticTools/config/state.d.ts

@@ -1,10 +1,10 @@
-export declare function resetRunScopedConfig(): void;
-export declare function isValidConfigKey(key: string): boolean;
-export declare function validateConfigValue(key: string, value: unknown): string | null;
-export declare function getConfigValue(key: string): unknown;
-export declare function getConfigDefault(key: string): unknown;
-export declare function listConfigKeys(): string[];
-export declare function getRunScopedConfigEntries(): IterableIterator<[string, unknown]>;
-export declare function setConfigValue(key: string, value: unknown, scope: string): void;
-export declare function resetConfigValue(key?: string): void;
+export declare const resetRunScopedConfig: () => void;
+export declare const isValidConfigKey: (key: string) => boolean;
+export declare const validateConfigValue: (key: string, value: unknown) => string | null;
+export declare const getConfigValue: (key: string) => unknown;
+export declare const getConfigDefault: (key: string) => unknown;
+export declare const listConfigKeys: () => string[];
+export declare const getRunScopedConfigEntries: () => IterableIterator<[string, unknown]>;
+export declare const setConfigValue: (key: string, value: unknown, scope: string) => void;
+export declare const resetConfigValue: (key?: string) => void;
 //# sourceMappingURL=state.d.ts.map

package/dist/agenticTools/config/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/config/state.ts"],"names":[],"mappings":"AAwDA,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKrD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAY9E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASnD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKrD;AAED,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAMzC;AAED,wBAAgB,yBAAyB,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE/E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAU/E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAMnD"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/config/state.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,oBAAoB,YAA6B,CAAC;AAC/D,eAAO,MAAM,gBAAgB,0BAAyB,CAAC;AACvD,eAAO,MAAM,mBAAmB,gDAA4B,CAAC;AAC7D,eAAO,MAAM,cAAc,0BAAuB,CAAC;AACnD,eAAO,MAAM,gBAAgB,0BAAyB,CAAC;AACvD,eAAO,MAAM,cAAc,gBAAuB,CAAC;AACnD,eAAO,MAAM,yBAAyB,2CAAkC,CAAC;AACzE,eAAO,MAAM,cAAc,sDAAuB,CAAC;AACnD,eAAO,MAAM,gBAAgB,wBAAyB,CAAC"}

package/dist/agenticTools/config/state.js

@@ -1,14 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetRunScopedConfig = resetRunScopedConfig;
-exports.isValidConfigKey = isValidConfigKey;
-exports.validateConfigValue = validateConfigValue;
-exports.getConfigValue = getConfigValue;
-exports.getConfigDefault = getConfigDefault;
-exports.listConfigKeys = listConfigKeys;
-exports.getRunScopedConfigEntries = getRunScopedConfigEntries;
-exports.setConfigValue = setConfigValue;
-exports.resetConfigValue = resetConfigValue;
+exports.resetConfigValue = exports.setConfigValue = exports.getRunScopedConfigEntries = exports.listConfigKeys = exports.getConfigDefault = exports.getConfigValue = exports.validateConfigValue = exports.isValidConfigKey = exports.resetRunScopedConfig = void 0;
 const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
 const EXTENDED_CONFIG_KEYS = new Set([
     "model",
@@ -16,20 +8,6 @@ const EXTENDED_CONFIG_KEYS = new Set([
     "breakpoint.autoApproveAfterN",
     "breakpoint.presentAlwaysApprove",
 ]);
-const BABYSITTER_CONFIG_KEYS = new Set([
-    "runsDir",
-    "maxIterations",
-    "qualityThreshold",
-    "timeout",
-    "logLevel",
-    "allowSecretLogs",
-    "hookTimeout",
-    "nodeTaskTimeout",
-    "clockStepMs",
-    "clockStartMs",
-    "layoutVersion",
-    "largeResultPreviewLimit",
-]);
 const CONFIG_KEY_TYPES = {
     runsDir: "string",
     maxIterations: "number",
@@ -46,82 +24,16 @@ const CONFIG_KEY_TYPES = {
     model: "string",
     provider: "string",
 };
-const VALID_LOG_LEVELS = new Set(["debug", "info", "warn", "error", "silent"]);
-const CONFIG_KEY_TO_ENV = {
-    runsDir: babysitter_sdk_1.CONFIG_ENV_VARS.RUNS_DIR,
-    maxIterations: babysitter_sdk_1.CONFIG_ENV_VARS.MAX_ITERATIONS,
-    qualityThreshold: babysitter_sdk_1.CONFIG_ENV_VARS.QUALITY_THRESHOLD,
-    timeout: babysitter_sdk_1.CONFIG_ENV_VARS.TIMEOUT,
-    logLevel: babysitter_sdk_1.CONFIG_ENV_VARS.LOG_LEVEL,
-    allowSecretLogs: babysitter_sdk_1.CONFIG_ENV_VARS.ALLOW_SECRET_LOGS,
-    hookTimeout: babysitter_sdk_1.CONFIG_ENV_VARS.HOOK_TIMEOUT,
-    nodeTaskTimeout: babysitter_sdk_1.CONFIG_ENV_VARS.NODE_TASK_TIMEOUT,
-};
-const runScopedConfig = new Map();
-function resetRunScopedConfig() {
-    runScopedConfig.clear();
-}
-function isValidConfigKey(key) {
-    return BABYSITTER_CONFIG_KEYS.has(key)
-        || EXTENDED_CONFIG_KEYS.has(key)
-        || key.startsWith("compression.")
-        || key.startsWith("breakpoint.");
-}
-function validateConfigValue(key, value) {
-    const expectedType = CONFIG_KEY_TYPES[key];
-    if (expectedType && typeof value !== expectedType) {
-        return `Expected '${key}' to be ${expectedType}, got ${typeof value}.`;
-    }
-    if (key === "logLevel" && typeof value === "string" && !VALID_LOG_LEVELS.has(value)) {
-        return `Invalid logLevel '${value}'. Must be one of: ${[...VALID_LOG_LEVELS].join(", ")}.`;
-    }
-    if (expectedType === "number" && typeof value === "number" && key !== "clockStartMs" && value <= 0) {
-        return `'${key}' must be a positive number.`;
-    }
-    return null;
-}
-function getConfigValue(key) {
-    if (runScopedConfig.has(key)) {
-        return runScopedConfig.get(key);
-    }
-    if (BABYSITTER_CONFIG_KEYS.has(key)) {
-        const config = (0, babysitter_sdk_1.getConfig)();
-        return config[key];
-    }
-    return undefined;
-}
-function getConfigDefault(key) {
-    if (BABYSITTER_CONFIG_KEYS.has(key)) {
-        return babysitter_sdk_1.DEFAULTS[key];
-    }
-    return undefined;
-}
-function listConfigKeys() {
-    return [...new Set([
-            ...BABYSITTER_CONFIG_KEYS,
-            ...EXTENDED_CONFIG_KEYS,
-            ...runScopedConfig.keys(),
-        ])];
-}
-function getRunScopedConfigEntries() {
-    return runScopedConfig.entries();
-}
-function setConfigValue(key, value, scope) {
-    if (scope === "global") {
-        const envKey = CONFIG_KEY_TO_ENV[key];
-        if (envKey) {
-            process.env[envKey] = String(value);
-        }
-        else {
-            process.env[`BABYSITTER_${key.replace(/\./g, "_").toUpperCase()}`] = String(value);
-        }
-    }
-    runScopedConfig.set(key, value);
-}
-function resetConfigValue(key) {
-    if (key) {
-        runScopedConfig.delete(key);
-        return;
-    }
-    runScopedConfig.clear();
-}
+const state = (0, babysitter_sdk_1.createScopedRuntimeConfigState)({
+    configKeyTypes: CONFIG_KEY_TYPES,
+    extendedConfigKeys: EXTENDED_CONFIG_KEYS,
+});
+exports.resetRunScopedConfig = state.resetRunScopedConfig;
+exports.isValidConfigKey = state.isValidConfigKey;
+exports.validateConfigValue = state.validateConfigValue;
+exports.getConfigValue = state.getConfigValue;
+exports.getConfigDefault = state.getConfigDefault;
+exports.listConfigKeys = state.listConfigKeys;
+exports.getRunScopedConfigEntries = state.getRunScopedConfigEntries;
+exports.setConfigValue = state.setConfigValue;
+exports.resetConfigValue = state.resetConfigValue;

package/dist/agenticTools/config/state.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state.test.d.ts.map

package/dist/agenticTools/config/state.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.test.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/config/state.test.ts"],"names":[],"mappings":""}

package/dist/agenticTools/config/state.test.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const state_1 = require("./state");
+(0, vitest_1.describe)("agent-core config state", () => {
+    (0, vitest_1.it)("does not write global config scope into process.env", () => {
+        const previous = process.env.BABYSITTER_LOG_LEVEL;
+        delete process.env.BABYSITTER_LOG_LEVEL;
+        try {
+            (0, state_1.resetConfigValue)();
+            (0, state_1.setConfigValue)("logLevel", "debug", "global");
+            (0, vitest_1.expect)(process.env.BABYSITTER_LOG_LEVEL).toBeUndefined();
+            (0, vitest_1.expect)((0, state_1.getConfigValue)("logLevel")).toBe("debug");
+        }
+        finally {
+            (0, state_1.resetConfigValue)();
+            if (previous === undefined)
+                delete process.env.BABYSITTER_LOG_LEVEL;
+            else
+                process.env.BABYSITTER_LOG_LEVEL = previous;
+        }
+    });
+});

package/dist/agenticTools/config/tool.js

@@ -19,7 +19,7 @@ function createConfigTool() {
             key: typebox_1.Type.Optional(typebox_1.Type.String({ description: "Config key path (dot notation for nested, e.g. 'compression.enabled')" })),
             value: typebox_1.Type.Optional(typebox_1.Type.Unknown({ description: "New value for set action" })),
             scope: typebox_1.Type.Optional(typebox_1.Type.Union([typebox_1.Type.Literal("run"), typebox_1.Type.Literal("global")], {
-                description: "Scope: 'run' (default, in-memory) or 'global' (env vars)",
+                description: "Scope: 'run' (default) or 'global' process-scoped config",
             })),
         }),
         execute: (_toolCallId, params) => {

package/dist/agenticTools/discovery/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/discovery/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGzE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,oBAAoB,EAAE,CA0ExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/discovery/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGzE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,oBAAoB,EAAE,CA4ExF"}

package/dist/agenticTools/discovery/tools.js

@@ -14,9 +14,9 @@ function createDiscoveryTools(options) {
                 max_results: typebox_1.Type.Optional(typebox_1.Type.Number({ description: "Maximum results to return (default 20)" })),
             }),
             execute: (_toolCallId, params) => {
-                const registry = options.deferredToolRegistry;
+                const registry = options.toolRegistry ?? options.deferredToolRegistry;
                 if (!registry) {
-                    return (0, results_1.errorResult)("Tool search is not available — no deferred tool registry configured.");
+                    return (0, results_1.errorResult)("Tool search is not available — no unified tool registry configured.");
                 }
                 const query = String(params.query ?? "");
                 const maxResults = typeof params.max_results === "number" ? params.max_results : 20;
@@ -29,6 +29,7 @@ function createDiscoveryTools(options) {
                         description: tool.description,
                         source: tool.source,
                         sourceQualifier: tool.sourceQualifier,
+                        metadata: tool.metadata,
                     })),
                 });
             },
@@ -43,9 +44,9 @@ function createDiscoveryTools(options) {
                 source_qualifier: typebox_1.Type.Optional(typebox_1.Type.String({ description: "Source qualifier (e.g. MCP server name)" })),
             }),
             execute: async (_toolCallId, params) => {
-                const registry = options.deferredToolRegistry;
+                const registry = options.toolRegistry ?? options.deferredToolRegistry;
                 if (!registry) {
-                    return (0, results_1.errorResult)("Tool fetch is not available — no deferred tool registry configured.");
+                    return (0, results_1.errorResult)("Tool fetch is not available — no unified tool registry configured.");
                 }
                 const toolName = String(params.name ?? "");
                 const validSources = new Set(["builtin", "mcp", "plugin", "custom"]);
@@ -62,6 +63,7 @@ function createDiscoveryTools(options) {
                     description: resolved.description,
                     source: resolved.source,
                     sourceQualifier: resolved.sourceQualifier,
+                    metadata: resolved.metadata,
                     inputSchema: resolved.schema.inputSchema,
                     outputSchema: resolved.schema.outputSchema,
                 });

package/dist/agenticTools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agenticTools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAexE,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,kBAAkB,GAAG,oBAAoB,EAAE,CAelG;AAED,wBAAgB,+BAA+B,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,IAAI,CAOzF;AAED,eAAO,MAAM,4BAA4B,uCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agenticTools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAoBxE,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,kBAAkB,GAAG,oBAAoB,EAAE,CAiClG;AAED,wBAAgB,+BAA+B,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,IAAI,CAWzF;AAED,eAAO,MAAM,4BAA4B,uCAAiC,CAAC"}

package/dist/agenticTools/index.js

@@ -14,9 +14,11 @@ const code_1 = require("./tools/code");
 const delegation_1 = require("./tools/delegation");
 const execution_1 = require("./tools/execution");
 const fileSystem_1 = require("./tools/fileSystem");
+const programmaticToolCalling_1 = require("./tools/programmaticToolCalling");
 const toolDefinitionScopes = new WeakMap();
+const toolDefinitionOwners = new WeakMap();
 function createAgentCoreToolDefinitions(options) {
-    const tools = [
+    const baseTools = [
         ...(0, fileSystem_1.createFileSystemTools)(options),
         ...(0, execution_1.createExecutionTools)(options),
         (0, tool_1.createBrowserTool)(),
@@ -27,15 +29,35 @@ function createAgentCoreToolDefinitions(options) {
         ...(0, tools_2.createDiscoveryTools)(options),
         ...(0, tools_3.createWebTools)(),
     ].map((tool) => (0, results_1.wrapToolDefinition)(tool, options.onToolUse));
+    options.toolRegistry?.registerAll?.(baseTools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        source: "builtin",
+        metadata: tool.metadata,
+    })));
+    const tools = (0, programmaticToolCalling_1.shouldEnableProgrammaticToolCalling)(options)
+        ? [
+            ...baseTools,
+            (0, results_1.wrapToolDefinition)((0, programmaticToolCalling_1.createProgrammaticToolCallingTool)(options, baseTools), options.onToolUse),
+        ]
+        : baseTools;
     toolDefinitionScopes.set(tools, options);
+    for (const tool of tools) {
+        toolDefinitionOwners.set(tool, options);
+    }
     return tools;
 }
 function disposeAgentCoreToolDefinitions(definitions) {
-    const options = toolDefinitionScopes.get(definitions);
+    const options = toolDefinitionScopes.get(definitions)
+        ?? definitions.map((definition) => toolDefinitionOwners.get(definition)).find(Boolean);
     if (!options) {
         return;
     }
     (0, state_1.disposeBackgroundRegistry)(options);
     toolDefinitionScopes.delete(definitions);
+    for (const definition of definitions) {
+        toolDefinitionOwners.delete(definition);
+    }
 }
 exports.createAgenticToolDefinitions = createAgentCoreToolDefinitions;

package/dist/agenticTools/shared/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/shared/paths.ts"],"names":[],"mappings":"AAGA,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA2BnD;AAED,wBAAgB,OAAO,CACrB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,OAAO,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,GAChB,IAAI,CA2BN"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/shared/paths.ts"],"names":[],"mappings":"AAGA,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA2BnD;AAED,wBAAgB,OAAO,CACrB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,OAAO,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,GAChB,IAAI,CA4BN"}

package/dist/agenticTools/shared/paths.js

@@ -93,7 +93,8 @@ function walkDir(directory, includeHidden, limit, results) {
     try {
         entries = fs.readdirSync(directory, { withFileTypes: true });
     }
-    catch {
+    catch (e) {
+        process.stderr.write(`[agent-core] walkDir: cannot read ${directory}: ${e instanceof Error ? e.message : String(e)}\n`);
         return;
     }
     for (const entry of entries) {

package/dist/agenticTools/shared/process.d.ts

@@ -2,11 +2,19 @@ export declare const DEFAULT_BASH_TIMEOUT = 120000;
 export declare const DEFAULT_SEARCH_TIMEOUT = 30000;
 export declare const MAX_READ_LINES = 10000;
 export declare function getRgPath(): string;
+export declare function resolveShellCommand(env?: NodeJS.ProcessEnv): {
+    shell: string;
+    argsFor(command: string): string[];
+};
 export declare function spawnAsync(command: string, args: string[], options: {
     cwd?: string;
     env?: Record<string, string>;
     timeout?: number;
     shell?: boolean;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+    onStdout?: (chunk: string) => void | Promise<void>;
+    onStderr?: (chunk: string) => void | Promise<void>;
 }): Promise<{
     stdout: string;
     stderr: string;

package/dist/agenticTools/shared/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/shared/process.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAC5C,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,cAAc,QAAS,CAAC;AAKrC,wBAAgB,SAAS,IAAI,MAAM,CAgBlC;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgE/D"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../../src/agenticTools/shared/process.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAC5C,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,cAAc,QAAS,CAAC;AAKrC,wBAAgB,SAAS,IAAI,MAAM,CAgBlC;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACpC,CAaA;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD,GACA,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAsE/D"}