@cursor/bdk 0.2.1

package/dist/internal/authored-loaders.js

@@ -0,0 +1,182 @@
+/**
+ * Process-wide module loaders for authored agent files.
+ *
+ * The CLI dynamically imports user TypeScript (`agent/agent.ts`,
+ * `agent/tools/*.ts`, `evals/**\/*.eval.ts`) at runtime, and plain Node
+ * cannot load `.ts` modules. Instead of requiring hosts to wrap the bin in
+ * `node --import tsx`, the bin (and programmatic `serve()`) registers tsx's
+ * ESM loader itself on startup.
+ *
+ * On compiled runs it additionally registers alias hooks so authored bare
+ * imports of the framework (`@cursor/bdk[/x]`) short-circuit to the same
+ * files the CLI loaded. Channel option WeakMaps
+ * (`getGitHubChannelOptions`, …) require that identity; letting tsx path-map
+ * or a second install win loads a duplicate module and breaks continuation /
+ * hosted-delivery lookups. Bare npm deps from monorepo `packages/agent-serve/`
+ * source still retry against this package (hosted factory engines).
+ * Source runs (tsx from the monorepo) skip both — the host loader and
+ * tsconfig paths already cover them.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { register as registerModuleHooks } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { CLI_COMMAND_NAME, frameworkAliases, isCompiledDistribution, packageRootDir, } from "./distribution.js";
+/**
+ * Cross-copy markers: a user project with its own `@cursor/bdk` install
+ * can load a second copy of this module in the same process; tsx and the
+ * alias hooks must only be registered once. The key strings are shared with
+ * already-published copies; renaming them would double-register.
+ */
+const TSX_REGISTERED_KEY = Symbol.for("cursor.agentkit.tsxRegistered");
+const ALIASES_REGISTERED_KEY = Symbol.for("cursor.agentkit.aliasesRegistered");
+/**
+ * ESM specifier for an authored agent/eval file.
+ *
+ * Node caches `import()` by URL for the life of the process, so a long-lived
+ * `agent-sdk dev` would otherwise keep serving the first load of eval files
+ * and agent modules. The mtime query string is ignored by the filesystem
+ * resolver and is the cache key.
+ *
+ * Truncate to an integer: vitest/esbuild treat the substring after the last
+ * `.` as a loader id, so `?mtime=1700000000000.4949` fails with
+ * `Invalid loader value: "4949"`. Named `mtime` rather than `t` so Vite does
+ * not treat it as its HMR timestamp and collapse the specifier to the path.
+ */
+export function authoredModuleSpecifier(absolutePath, mtimeMs) {
+    const url = pathToFileURL(absolutePath);
+    url.searchParams.set("mtime", String(Math.trunc(mtimeMs)));
+    return url.href;
+}
+export function partitionFrameworkAliases(aliases) {
+    const directAliases = {};
+    const sourceFallbackAliases = [];
+    for (const [specifier, url] of Object.entries(aliases)) {
+        if (existsSync(fileURLToPath(url))) {
+            directAliases[specifier] = url;
+        }
+        else {
+            sourceFallbackAliases.push(specifier);
+        }
+    }
+    return { directAliases, sourceFallbackAliases };
+}
+/**
+ * Dynamically import an authored TypeScript/JavaScript module, re-reading it
+ * from disk when the file's mtime has changed since the last import.
+ */
+export function importAuthoredModule(absolutePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (yield stat(absolutePath)).mtimeMs;
+        }
+        catch (_a) {
+            // import() reports the real missing-file error.
+        }
+        const loaded = yield import(authoredModuleSpecifier(absolutePath, mtimeMs));
+        if (typeof loaded !== "object" || loaded === null) {
+            throw new Error(`authored module is not an object: ${absolutePath}`);
+        }
+        return loaded;
+    });
+}
+let registration;
+/**
+ * Install the runtime loaders for authored agent files. Idempotent; called
+ * from the CLI entry before any command runs, and from `serve()` and the
+ * discovery APIs for programmatic embedders. Concurrent callers share one
+ * registration and all wait for it to finish.
+ */
+export function registerAuthoredModuleLoaders() {
+    if (!isCompiledDistribution()) {
+        return Promise.resolve();
+    }
+    registration !== null && registration !== void 0 ? registration : (registration = (() => __awaiter(this, void 0, void 0, function* () {
+        yield registerTsxLoader();
+        registerFrameworkAliases();
+    }))());
+    return registration;
+}
+function registerTsxLoader() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Escape hatch for hosts that precompile authored files to .js (or bring
+        // their own loader) and don't want tsx hooked into module resolution.
+        if (process.env.AGENT_SERVE_DISABLE_TSX === "1") {
+            return;
+        }
+        if (tsxAlreadyActive()) {
+            return;
+        }
+        try {
+            const tsx = (yield import("tsx/esm/api"));
+            if (typeof tsx.register !== "function") {
+                throw new Error("tsx/esm/api has no register export");
+            }
+            tsx.register();
+            globalThis[TSX_REGISTERED_KEY] = true;
+        }
+        catch (error) {
+            process.stderr.write(`[${CLI_COMMAND_NAME}] tsx loader unavailable (${error instanceof Error ? error.message : String(error)}); authored TypeScript files will not load — install tsx or precompile the agent to .js\n`);
+        }
+    });
+}
+/**
+ * Whether a tsx loader is already installed process-wide: by a previous call
+ * from another copy of this module, or by the host command line (the Docker
+ * flow still runs `node --import tsx dist/bin/agent-serve.js`).
+ */
+function tsxAlreadyActive() {
+    var _a;
+    var _b;
+    if (globalThis[TSX_REGISTERED_KEY] === true) {
+        return true;
+    }
+    const hostArgs = [...process.execArgv, ...((_b = (_a = process.env.NODE_OPTIONS) === null || _a === void 0 ? void 0 : _a.split(/\s+/)) !== null && _b !== void 0 ? _b : [])];
+    for (let i = 0; i < hostArgs.length; i++) {
+        const arg = hostArgs[i];
+        if (arg === "--import" || arg === "--loader" || arg === "--require") {
+            const value = hostArgs[i + 1];
+            if (value === "tsx" || (value === null || value === void 0 ? void 0 : value.startsWith("tsx/"))) {
+                return true;
+            }
+        }
+        else if (arg !== undefined && /^--(import|loader|require)=tsx(\/|$)/.test(arg)) {
+            return true;
+        }
+    }
+    return false;
+}
+function registerFrameworkAliases() {
+    const markers = globalThis;
+    if (markers[ALIASES_REGISTERED_KEY] === true) {
+        return;
+    }
+    const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
+    const { directAliases, sourceFallbackAliases } = partitionFrameworkAliases(frameworkAliases());
+    const data = {
+        directAliases,
+        // Internal-only exports stay out of the public package. When one is
+        // mounted by an agent in this source checkout, resolve that one import
+        // through the checkout's `anysphere-source` export instead.
+        sourceFallbackAliases,
+        // Hosted factory agents relative-import this package's src/ from a
+        // monorepo checkout while npm install ran only in the agent directory.
+        // Bare specifiers from that tree retry against this package.json.
+        sourceTreeFallbackParentURL: pathToFileURL(join(packageRootDir(), "package.json")).href,
+    };
+    // `node:module`'s register() is synchronous: it blocks until the hooks
+    // thread has initialized, so the aliases are active when it returns.
+    registerModuleHooks(hooksUrl, { data });
+    markers[ALIASES_REGISTERED_KEY] = true;
+}

package/dist/internal/bounded-int.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared validation for optional config ceilings (playground windows, etc.).
+ */
+export declare function normalizePositiveInt(value: unknown, options: {
+    /** e.g. `evals.config.ts: maxPlaygroundRuns` */
+    label: string;
+    max: number;
+    /** Override the default "exceeds the hard limit" message body after the label. */
+    maxMessage?: string;
+}): number;
+//# sourceMappingURL=bounded-int.d.ts.map

package/dist/internal/bounded-int.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-int.d.ts","sourceRoot":"","sources":["../../src/internal/bounded-int.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IACP,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,MAAM,CAUR"}

package/dist/internal/bounded-int.js

@@ -0,0 +1,13 @@
+/**
+ * Shared validation for optional config ceilings (playground windows, etc.).
+ */
+export function normalizePositiveInt(value, options) {
+    var _a;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new Error(`${options.label} must be a positive integer (got ${String(value)})`);
+    }
+    if (value > options.max) {
+        throw new Error((_a = options.maxMessage) !== null && _a !== void 0 ? _a : `${options.label} ${value} exceeds the hard limit of ${options.max}`);
+    }
+    return value;
+}

package/dist/internal/bounded.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Bounded-concurrency map, in input order. Local rather than
+ * `@anysphere/utils`: this published package cannot depend on monorepo
+ * internals.
+ */
+export declare function mapBounded<T, R>(items: readonly T[], max: number, run: (item: T) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=bounded.d.ts.map

package/dist/internal/bounded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded.d.ts","sourceRoot":"","sources":["../../src/internal/bounded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,EACnC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,EAAE,CAAC,CAed"}

package/dist/internal/bounded.js

@@ -0,0 +1,32 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * Bounded-concurrency map, in input order. Local rather than
+ * `@anysphere/utils`: this published package cannot depend on monorepo
+ * internals.
+ */
+export function mapBounded(items, max, run) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const out = new Array(items.length);
+        let nextIndex = 0;
+        const workers = Array.from({ length: Math.min(max, items.length) }, () => __awaiter(this, void 0, void 0, function* () {
+            for (;;) {
+                const index = nextIndex;
+                nextIndex += 1;
+                if (index >= items.length) {
+                    return;
+                }
+                out[index] = yield run(items[index]);
+            }
+        }));
+        yield Promise.all(workers);
+        return out;
+    });
+}

package/dist/internal/brand.d.ts

@@ -0,0 +1,6 @@
+import type { BrandedDefinition, DefinitionKind } from "../types.js";
+export declare const DEFINITION_BRAND_FIELD = "__agentServe";
+export declare function brandDefinition<K extends DefinitionKind, T extends object>(kind: K, definition: T): T & BrandedDefinition<K>;
+export declare function getDefinitionKind(value: unknown): DefinitionKind | undefined;
+export declare function isDefinitionOfKind<K extends DefinitionKind>(value: unknown, kind: K): value is BrandedDefinition<K>;
+//# sourceMappingURL=brand.d.ts.map

package/dist/internal/brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/internal/brand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAErE,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD,wBAAgB,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,MAAM,EACxE,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,CAAC,GACZ,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE1B;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAS5E;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,cAAc,EACzD,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,CAAC,GACN,KAAK,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAE/B"}

package/dist/internal/brand.js

@@ -0,0 +1,17 @@
+export const DEFINITION_BRAND_FIELD = "__agentServe";
+export function brandDefinition(kind, definition) {
+    return Object.assign(Object.assign({}, definition), { [DEFINITION_BRAND_FIELD]: kind });
+}
+export function getDefinitionKind(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const kind = value[DEFINITION_BRAND_FIELD];
+    if (typeof kind !== "string") {
+        return undefined;
+    }
+    return kind;
+}
+export function isDefinitionOfKind(value, kind) {
+    return getDefinitionKind(value) === kind;
+}

package/dist/internal/browser-origin-guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CSRF guard for mutating serve HTTP requests.
+ *
+ * Default serve trusts loopback (`localDevStrict`). CLI, webhooks, and the
+ * control plane send no `Origin`. A page in the developer's browser is also
+ * loopback, and a CORS-simple POST (e.g. text/plain) skips preflight, so any
+ * site they visit can drive sessions, tools, and channel routes.
+ *
+ * `Origin` is the primary signal (forbidden header; `Origin: null` never
+ * matches). No browser signals means a non-browser client. `Sec-Fetch-Site`
+ * is the fallback when Origin is omitted.
+ */
+export type BrowserOriginGuardOptions = {
+    /** Extra trusted `host[:port]` values (e.g. `--public-url` behind a Host-rewriting proxy). */
+    allowedOriginHosts?: ReadonlySet<string>;
+};
+export declare function browserOriginGuardOptionsForPublicUrl(publicUrl: string | undefined): BrowserOriginGuardOptions | undefined;
+export declare function isTrustedBrowserMutation(request: Request, options?: BrowserOriginGuardOptions): boolean;
+//# sourceMappingURL=browser-origin-guard.d.ts.map

package/dist/internal/browser-origin-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-origin-guard.d.ts","sourceRoot":"","sources":["../../src/internal/browser-origin-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,yBAAyB,GAAG;IACtC,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF,wBAAgB,qCAAqC,CACnD,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,yBAAyB,GAAG,SAAS,CASvC;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAcT"}

package/dist/internal/browser-origin-guard.js

@@ -0,0 +1,51 @@
+/**
+ * CSRF guard for mutating serve HTTP requests.
+ *
+ * Default serve trusts loopback (`localDevStrict`). CLI, webhooks, and the
+ * control plane send no `Origin`. A page in the developer's browser is also
+ * loopback, and a CORS-simple POST (e.g. text/plain) skips preflight, so any
+ * site they visit can drive sessions, tools, and channel routes.
+ *
+ * `Origin` is the primary signal (forbidden header; `Origin: null` never
+ * matches). No browser signals means a non-browser client. `Sec-Fetch-Site`
+ * is the fallback when Origin is omitted.
+ */
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+export function browserOriginGuardOptionsForPublicUrl(publicUrl) {
+    if (publicUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return { allowedOriginHosts: new Set([new URL(publicUrl).host]) };
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+export function isTrustedBrowserMutation(request, options) {
+    if (SAFE_METHODS.has(request.method.toUpperCase())) {
+        return true;
+    }
+    const origin = request.headers.get("origin");
+    if (origin !== null) {
+        return originHostMatches(origin, request.url, options === null || options === void 0 ? void 0 : options.allowedOriginHosts);
+    }
+    // Some Safari versions omit Origin on same-origin POST but still send Fetch Metadata.
+    const secFetchSite = request.headers.get("sec-fetch-site");
+    if (secFetchSite !== null) {
+        return secFetchSite === "same-origin" || secFetchSite === "none";
+    }
+    return true;
+}
+function originHostMatches(origin, requestUrl, extraAllowedHosts) {
+    let originUrl;
+    let selfUrl;
+    try {
+        originUrl = new URL(origin);
+        selfUrl = new URL(requestUrl);
+    }
+    catch (_a) {
+        return false;
+    }
+    return originUrl.host === selfUrl.host || (extraAllowedHosts === null || extraAllowedHosts === void 0 ? void 0 : extraAllowedHosts.has(originUrl.host)) === true;
+}

package/dist/internal/builtin-tools/artifacts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `tag_artifact` built-in tool, enabled by
+ * `defineArtifacts({ agentTool: true })` rather than
+ * `AgentConfig.builtinTools`: its input schema and description are
+ * generated from the declared kinds registry.
+ */
+import type { ArtifactsConfig, ToolDefinition } from "../../types.js";
+export declare const TAG_ARTIFACT_TOOL_NAME = "tag_artifact";
+export declare function tagArtifactTool(config: ArtifactsConfig): ToolDefinition;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/internal/builtin-tools/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/internal/builtin-tools/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEtE,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAmBrD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,CA+BvE"}

package/dist/internal/builtin-tools/artifacts.js

@@ -0,0 +1,66 @@
+/**
+ * The `tag_artifact` built-in tool, enabled by
+ * `defineArtifacts({ agentTool: true })` rather than
+ * `AgentConfig.builtinTools`: its input schema and description are
+ * generated from the declared kinds registry.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { z } from "zod";
+import { defineTool } from "../../tools.js";
+export const TAG_ARTIFACT_TOOL_NAME = "tag_artifact";
+function kindVariant(name, schema) {
+    return z.object({
+        kind: z.literal(name),
+        data: schema !== null && schema !== void 0 ? schema : z.object({}).passthrough().describe("Freeform JSON object payload for this kind."),
+        title: z.string().optional().describe("Short human-readable label shown in artifact lists."),
+        key: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Stable key, unique across kinds. Reusing it replaces that record instead of adding a new one."),
+    });
+}
+export function tagArtifactTool(config) {
+    var _a;
+    const kinds = Object.entries((_a = config.kinds) !== null && _a !== void 0 ? _a : {});
+    const [first, ...rest] = kinds.map(([name, kind]) => kindVariant(name, kind.schema));
+    if (first === undefined) {
+        // Discovery already errors on agentTool without kinds.
+        throw new Error("tag_artifact requires at least one declared artifact kind");
+    }
+    const description = [
+        "Tag a finished output as an artifact. Artifacts persist across sessions and are listed for the people supervising this agent.",
+        "Kinds:",
+        ...kinds.map(([name, kind]) => `- ${name}: ${kind.description}`),
+    ].join("\n");
+    return defineTool({
+        description,
+        inputSchema: z.discriminatedUnion("kind", [first, ...rest]),
+        execute(input, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const record = yield ctx.artifacts.tag({
+                    kind: input.kind,
+                    data: input.data,
+                    title: input.title,
+                    key: input.key,
+                    source: "model",
+                });
+                return {
+                    tagged: true,
+                    id: record.id,
+                    kind: record.kind,
+                    key: record.key,
+                };
+            });
+        },
+    });
+}

package/dist/internal/builtin-tools/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Built-in tools (`AgentConfig.builtinTools`): framework-provided
+ * model-facing tools, materialized as ordinary server tools at discovery
+ * time so turns, direct calls, `info`, and the playground treat them
+ * exactly like authored tools.
+ */
+import type { ArtifactsConfig, BuiltinToolsConfig, DiscoveredTool } from "../../types.js";
+export { TAG_ARTIFACT_TOOL_NAME } from "./artifacts.js";
+/** Resolve the enabled built-in tools, in stable catalog order. */
+export declare function builtinTools(config: BuiltinToolsConfig | undefined): DiscoveredTool[];
+/**
+ * The `tag_artifact` built-in, enabled by `defineArtifacts({ agentTool:
+ * true })` (not `AgentConfig.builtinTools` — the tool is generated from
+ * the kinds registry). Undefined without kinds: discovery already errors.
+ */
+export declare function artifactBuiltinTool(config: ArtifactsConfig | undefined): DiscoveredTool | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/internal/builtin-tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/builtin-tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,cAAc,EAAE,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,cAAc,GAAG,SAAS,CAK5B"}

package/dist/internal/builtin-tools/index.js

@@ -0,0 +1,40 @@
+/**
+ * Built-in tools (`AgentConfig.builtinTools`): framework-provided
+ * model-facing tools, materialized as ordinary server tools at discovery
+ * time so turns, direct calls, `info`, and the playground treat them
+ * exactly like authored tools.
+ */
+import { toolInputJsonSchema } from "../json-schema.js";
+import { TAG_ARTIFACT_TOOL_NAME, tagArtifactTool } from "./artifacts.js";
+import { reminderTools } from "./reminders.js";
+export { TAG_ARTIFACT_TOOL_NAME } from "./artifacts.js";
+/** Resolve the enabled built-in tools, in stable catalog order. */
+export function builtinTools(config) {
+    const tools = [];
+    if ((config === null || config === void 0 ? void 0 : config.reminders) === true) {
+        tools.push(...toDiscovered(reminderTools));
+    }
+    return tools;
+}
+/**
+ * The `tag_artifact` built-in, enabled by `defineArtifacts({ agentTool:
+ * true })` (not `AgentConfig.builtinTools` — the tool is generated from
+ * the kinds registry). Undefined without kinds: discovery already errors.
+ */
+export function artifactBuiltinTool(config) {
+    var _a;
+    if ((config === null || config === void 0 ? void 0 : config.agentTool) !== true || Object.keys((_a = config.kinds) !== null && _a !== void 0 ? _a : {}).length === 0) {
+        return undefined;
+    }
+    return toDiscovered({ [TAG_ARTIFACT_TOOL_NAME]: tagArtifactTool(config) })[0];
+}
+function toDiscovered(byName) {
+    return Object.entries(byName).map(([name, definition]) => ({
+        name,
+        description: definition.description,
+        inputSchema: toolInputJsonSchema(definition.inputSchema),
+        execution: "server",
+        needsApproval: definition.needsApproval === true || typeof definition.needsApproval === "function",
+        definition,
+    }));
+}

package/dist/internal/builtin-tools/reminders.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Built-in reminder tools (`builtinTools: { reminders: true }`): durable
+ * wakes bound to the current conversation over `host.reminders`. The
+ * framework's reminder fire prompt tells the model to call
+ * `reminders_cancel` by name, so these tool names must not change.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const reminderTools: Record<string, ToolDefinition>;
+//# sourceMappingURL=reminders.d.ts.map

package/dist/internal/builtin-tools/reminders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminders.d.ts","sourceRoot":"","sources":["../../../src/internal/builtin-tools/reminders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAA8C,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAmIjG,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAIxD,CAAC"}

package/dist/internal/builtin-tools/reminders.js

@@ -0,0 +1,134 @@
+/**
+ * Built-in reminder tools (`builtinTools: { reminders: true }`): durable
+ * wakes bound to the current conversation over `host.reminders`. The
+ * framework's reminder fire prompt tells the model to call
+ * `reminders_cancel` by name, so these tool names must not change.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { z } from "zod";
+import { defineTool } from "../../tools.js";
+import { parseDuration } from "../duration.js";
+/** Floor for model-armed recurring wakes: each fire spends a model turn. */
+const MIN_EVERY_MS = 60000;
+function api(ctx) {
+    const reminders = ctx.host.reminders;
+    if (reminders === undefined) {
+        throw new Error("Reminders are disabled on this host.");
+    }
+    return reminders;
+}
+function conversation(ctx) {
+    const token = ctx.session.continuationKey;
+    if (token == null) {
+        throw new Error("This session is not bound to a followable conversation; reminders cannot wake it.");
+    }
+    return { channelId: ctx.session.channelId, continuationToken: token };
+}
+/** Reminders visible to this conversation (tokens are channel-local). */
+function listMine(ctx, status) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const conv = conversation(ctx);
+        const all = yield api(ctx).list({
+            status,
+            continuationToken: conv.continuationToken,
+        });
+        return all.filter(r => r.channelId === conv.channelId);
+    });
+}
+function toResult(r) {
+    return {
+        reminderId: r.id,
+        purpose: r.purpose,
+        schedule: `${r.scheduleKind} ${r.scheduleValue}`,
+        nextFireAt: r.nextFireAt,
+        until: r.untilPrompt,
+    };
+}
+const create = defineTool({
+    description: "Set a reminder for yourself in this conversation. When it fires, your prompt returns here as a follow-up turn. Use it to re-check state that needs time to settle. One-shot (delay) or recurring (every).",
+    inputSchema: z.object({
+        prompt: z
+            .string()
+            .min(1)
+            .describe("What to do when you wake. Keep it generic ('re-check CI and report only if the status changed') and re-read live state on wake instead of replaying stale details."),
+        delay: z
+            .string()
+            .optional()
+            .describe('One-shot: wake once after this duration, e.g. "20m" or "2h". Provide exactly one of delay or every.'),
+        every: z
+            .string()
+            .optional()
+            .describe('Recurring: wake at this interval, e.g. "30m", until cancelled or the stop condition is met. Provide exactly one of delay or every.'),
+        purpose: z
+            .string()
+            .min(1)
+            .max(64)
+            .optional()
+            .describe('Short slug naming the reminder, e.g. "ci_recheck". Defaults to "follow_up".'),
+        until: z
+            .string()
+            .optional()
+            .describe("Recurring only: plain-language stop condition you will honor by calling reminders_cancel, e.g. 'Cancel once CI is green or the PR is merged.'"),
+    }),
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if ((input.delay !== undefined) === (input.every !== undefined)) {
+                throw new Error("Provide exactly one of delay or every.");
+            }
+            if (input.every !== undefined && parseDuration(input.every) < MIN_EVERY_MS) {
+                throw new Error('Recurring reminders must use every >= "1m".');
+            }
+            const conv = conversation(ctx);
+            const reminder = yield api(ctx).create({
+                purpose: (_a = input.purpose) !== null && _a !== void 0 ? _a : "follow_up",
+                channelId: conv.channelId,
+                continuationToken: conv.continuationToken,
+                prompt: input.prompt,
+                delay: input.delay,
+                every: input.every,
+                until: input.until,
+            });
+            return toResult(reminder);
+        });
+    },
+});
+const list = defineTool({
+    description: "List the armed reminders bound to this conversation. Check before arming duplicates.",
+    inputSchema: z.object({}),
+    execute(_input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return { reminders: (yield listMine(ctx, "armed")).map(toResult) };
+        });
+    },
+});
+const cancel = defineTool({
+    description: "Cancel one of this conversation's reminders by id, the moment its stop condition is met or it is no longer needed.",
+    inputSchema: z.object({
+        id: z.string().min(1).describe("Reminder id from reminders_create or reminders_list."),
+    }),
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const mine = (yield listMine(ctx)).find(r => r.id === input.id);
+            if (mine === undefined) {
+                throw new Error(`No reminder "${input.id}" in this conversation.`);
+            }
+            const cancelled = yield api(ctx).cancel(input.id);
+            return { reminderId: input.id, status: (_a = cancelled === null || cancelled === void 0 ? void 0 : cancelled.status) !== null && _a !== void 0 ? _a : "cancelled" };
+        });
+    },
+});
+export const reminderTools = {
+    reminders_create: create,
+    reminders_list: list,
+    reminders_cancel: cancel,
+};