@cursor/july 0.1.2 → 0.1.4

package/dist/internal/update-check.js

@@ -0,0 +1,431 @@
+/**
+ * Outdated-version warning + `agentkit update`.
+ *
+ * Every CLI run of a published install compares its own version against the
+ * npm registry's `latest` dist-tag and warns on stderr when behind. The
+ * registry lookup is cached under the config dir
+ * (`~/.config/agent-serve/update-check.json`) so most runs never touch the
+ * network; a stale cache refreshes inline under a short timeout, and any
+ * network failure is silent (the warning is best-effort, never a blocker).
+ *
+ * `agentkit update` re-runs the lookup fresh, figures out how this copy was
+ * installed (global npm/pnpm/yarn/bun, or a project dependency), and runs the
+ * matching install command.
+ */
+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 { spawn } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { z } from "zod";
+import { configDirPath } from "./cursor/credentials.js";
+import { describeError } from "./describe-error.js";
+import { CLI_COMMAND_NAME, isCompiledDistribution, PACKAGE_NAME, packageRootDir, packageVersion, } from "./distribution.js";
+import { stderrPalette } from "./terminal-style.js";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+/** Refresh the registry lookup at most this often. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Inline refresh budget; a slow registry must not stall the command. */
+const WARN_FETCH_TIMEOUT_MS = 1500;
+/** `agentkit update` runs interactively, so it can afford a real timeout. */
+const UPDATE_FETCH_TIMEOUT_MS = 10000;
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(version.trim());
+    if (match === null) {
+        return undefined;
+    }
+    return {
+        release: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] === undefined ? [] : match[4].split("."),
+    };
+}
+/**
+ * Semver-style ordering: negative when `a < b`, 0 when equal, positive when
+ * `a > b`. Unparseable versions compare equal (never warn on garbage).
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (pa === undefined || pb === undefined) {
+        return 0;
+    }
+    for (let i = 0; i < 3; i++) {
+        const diff = pa.release[i] - pb.release[i];
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    // A release outranks any prerelease of the same triple.
+    if (pa.prerelease.length === 0 || pb.prerelease.length === 0) {
+        return pb.prerelease.length - pa.prerelease.length;
+    }
+    const len = Math.max(pa.prerelease.length, pb.prerelease.length);
+    for (let i = 0; i < len; i++) {
+        const ia = pa.prerelease[i];
+        const ib = pb.prerelease[i];
+        // A longer prerelease list outranks its prefix (1.0.0-a.1 > 1.0.0-a).
+        if (ia === undefined) {
+            return -1;
+        }
+        if (ib === undefined) {
+            return 1;
+        }
+        const na = /^\d+$/.test(ia) ? Number(ia) : undefined;
+        const nb = /^\d+$/.test(ib) ? Number(ib) : undefined;
+        if (na !== undefined && nb !== undefined) {
+            if (na !== nb) {
+                return na - nb;
+            }
+        }
+        else if (na !== undefined) {
+            return -1; // numeric identifiers sort before alphanumeric ones
+        }
+        else if (nb !== undefined) {
+            return 1;
+        }
+        else if (ia !== ib) {
+            return ia < ib ? -1 : 1;
+        }
+    }
+    return 0;
+}
+// ============================================================================
+// Registry lookup
+// ============================================================================
+const distTagResponseSchema = z.object({ version: z.string() });
+/**
+ * Latest published version of the package, from the registry's `latest`
+ * dist-tag. Returns undefined on any failure (offline, 404 pre-publish, …).
+ */
+export function fetchLatestPublishedVersion(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const fetchImpl = (_a = options === null || options === void 0 ? void 0 : options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        const packageName = (_b = options === null || options === void 0 ? void 0 : options.packageName) !== null && _b !== void 0 ? _b : PACKAGE_NAME;
+        // Scoped names keep the `@` but encode the `/` for the registry path.
+        const url = `${NPM_REGISTRY_URL}/${packageName.replace("/", "%2F")}/latest`;
+        try {
+            const response = yield fetchImpl(url, {
+                headers: { accept: "application/json" },
+                signal: AbortSignal.timeout((_c = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _c !== void 0 ? _c : WARN_FETCH_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                return undefined;
+            }
+            const body = distTagResponseSchema.safeParse(yield response.json());
+            if (!body.success || parseVersion(body.data.version) === undefined) {
+                return undefined;
+            }
+            return body.data.version;
+        }
+        catch (_d) {
+            return undefined;
+        }
+    });
+}
+// ============================================================================
+// Cache (one JSON file next to credentials.json)
+// ============================================================================
+const cacheSchema = z.object({
+    /** Epoch ms of the last registry lookup attempt (success or not). */
+    checkedAt: z.number(),
+    /** Last version the registry reported; absent when lookups keep failing. */
+    latestVersion: z.string().optional(),
+});
+export function updateCheckCachePath(configDir) {
+    return join(configDir !== null && configDir !== void 0 ? configDir : configDirPath(), "update-check.json");
+}
+export function readUpdateCheckCache(configDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let raw;
+        try {
+            raw = yield readFile(updateCheckCachePath(configDir), "utf8");
+        }
+        catch (_a) {
+            return undefined;
+        }
+        try {
+            const parsed = cacheSchema.safeParse(JSON.parse(raw));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch (_b) {
+            return undefined;
+        }
+    });
+}
+export function writeUpdateCheckCache(cache, configDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = updateCheckCachePath(configDir);
+        try {
+            yield mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            yield writeFile(path, `${JSON.stringify(cache, null, 2)}\n`);
+        }
+        catch (_a) {
+            // Best-effort; a read-only config dir just means re-checking next run.
+        }
+    });
+}
+/**
+ * Print an outdated-version warning to stderr when a newer release exists.
+ *
+ * Never throws and never blocks longer than {@link WARN_FETCH_TIMEOUT_MS}.
+ * Suppressed on source-checkout runs (there is no installed copy to update),
+ * in CI, and via NO_UPDATE_NOTIFIER / AGENT_SERVE_NO_UPDATE_CHECK.
+ */
+export function warnIfOutdated(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        const env = (_a = options === null || options === void 0 ? void 0 : options.env) !== null && _a !== void 0 ? _a : process.env;
+        if (isTruthyEnv(env.AGENT_SERVE_NO_UPDATE_CHECK) ||
+            isTruthyEnv(env.NO_UPDATE_NOTIFIER) ||
+            isTruthyEnv(env.CI)) {
+            return;
+        }
+        if ((options === null || options === void 0 ? void 0 : options.force) !== true && !isCompiledDistribution()) {
+            return;
+        }
+        const now = (_b = options === null || options === void 0 ? void 0 : options.now) !== null && _b !== void 0 ? _b : Date.now();
+        const currentVersion = (_c = options === null || options === void 0 ? void 0 : options.currentVersion) !== null && _c !== void 0 ? _c : packageVersion();
+        const cached = yield readUpdateCheckCache(options === null || options === void 0 ? void 0 : options.configDir);
+        let latestVersion = cached === null || cached === void 0 ? void 0 : cached.latestVersion;
+        const fresh = cached !== undefined && now - cached.checkedAt < CHECK_INTERVAL_MS;
+        if (!fresh) {
+            const fetched = yield fetchLatestPublishedVersion({
+                fetchImpl: options === null || options === void 0 ? void 0 : options.fetchImpl,
+                timeoutMs: WARN_FETCH_TIMEOUT_MS,
+            });
+            latestVersion = fetched !== null && fetched !== void 0 ? fetched : latestVersion;
+            // checkedAt always advances so a flaky registry backs off to one
+            // attempt per interval instead of one per command.
+            yield writeUpdateCheckCache({ checkedAt: now, latestVersion }, options === null || options === void 0 ? void 0 : options.configDir);
+        }
+        if (latestVersion === undefined ||
+            compareVersions(currentVersion, latestVersion) >= 0) {
+            return;
+        }
+        const c = stderrPalette();
+        const err = (_d = options === null || options === void 0 ? void 0 : options.err) !== null && _d !== void 0 ? _d : ((text) => void process.stderr.write(text));
+        err(`${c.yellow("warning:")} ${CLI_COMMAND_NAME} ${currentVersion} is outdated (latest is ${latestVersion}). Run \`${CLI_COMMAND_NAME} update\` to upgrade.\n`);
+    });
+}
+function isTruthyEnv(value) {
+    return value !== undefined && value !== "" && value !== "0";
+}
+/**
+ * Figure out how the running copy was installed and which command upgrades
+ * it. Detection is path-shape based (global stores have recognizable
+ * layouts), then falls back to walking up to the project that declares the
+ * dependency. Returns undefined for layouts we cannot safely upgrade
+ * (npx cache, unrecognized stores).
+ */
+export function detectUpdateCommand(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const packageName = (_a = args.packageName) !== null && _a !== void 0 ? _a : PACKAGE_NAME;
+        const spec = `${packageName}@latest`;
+        const posixRoot = args.packageRoot.split(sep).join("/");
+        // npx / pnpm dlx caches are ephemeral; a fresh `npx agentkit` already
+        // resolves latest, and upgrading the cache entry in place helps nobody.
+        if (posixRoot.includes("/_npx/") || posixRoot.includes("/.pnpm-store/")) {
+            return undefined;
+        }
+        if (posixRoot.includes("/pnpm/global/")) {
+            return {
+                cmd: "pnpm",
+                args: ["add", "-g", spec],
+                reason: "installed with pnpm --global",
+            };
+        }
+        if (posixRoot.includes("/.bun/install/global/")) {
+            return {
+                cmd: "bun",
+                args: ["add", "-g", spec],
+                reason: "installed with bun --global",
+            };
+        }
+        if (posixRoot.includes("/yarn/global/") ||
+            posixRoot.includes("/.config/yarn/global/")) {
+            return {
+                cmd: "yarn",
+                args: ["global", "add", spec],
+                reason: "installed with yarn global",
+            };
+        }
+        // A project that depends on the package: upgrade the dependency there,
+        // with whichever package manager the lockfile says the project uses.
+        const projectDir = yield findDependingProjectDir(args.packageRoot, packageName);
+        if (projectDir !== undefined) {
+            const pm = yield detectProjectPackageManager(projectDir);
+            const command = pm === "pnpm"
+                ? { cmd: "pnpm", args: ["add", spec] }
+                : pm === "yarn"
+                    ? { cmd: "yarn", args: ["add", spec] }
+                    : pm === "bun"
+                        ? { cmd: "bun", args: ["add", spec] }
+                        : { cmd: "npm", args: ["install", spec] };
+            return Object.assign(Object.assign({}, command), { cwd: projectDir, reason: `project dependency in ${projectDir}` });
+        }
+        // Global npm layout: <prefix>/lib/node_modules/<name> (or <prefix>\
+        // node_modules\<name> on Windows), with no depending project above it.
+        if (posixRoot.includes("/node_modules/")) {
+            return {
+                cmd: "npm",
+                args: ["install", "-g", spec],
+                reason: "installed with npm --global",
+            };
+        }
+        return undefined;
+    });
+}
+/**
+ * Nearest ancestor with a package.json that declares `packageName` as a
+ * dependency. Skips directories inside node_modules (pnpm's virtual store
+ * nests package.json files that are not the user's project).
+ */
+function findDependingProjectDir(packageRoot, packageName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let dir = dirname(packageRoot);
+        for (let depth = 0; depth < 30; depth++) {
+            const parent = dirname(dir);
+            if (parent === dir) {
+                return undefined;
+            }
+            const inNodeModules = dir
+                .split(sep)
+                .some((part) => part === "node_modules" || part === ".pnpm");
+            if (!inNodeModules && (yield declaresDependency(dir, packageName))) {
+                return dir;
+            }
+            dir = parent;
+        }
+        return undefined;
+    });
+}
+function declaresDependency(dir, packageName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        let raw;
+        try {
+            raw = yield readFile(join(dir, "package.json"), "utf8");
+        }
+        catch (_c) {
+            return false;
+        }
+        const manifestSchema = z.object({
+            dependencies: z.record(z.string()).optional(),
+            devDependencies: z.record(z.string()).optional(),
+        });
+        try {
+            const parsed = manifestSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success) {
+                return false;
+            }
+            return (((_a = parsed.data.dependencies) === null || _a === void 0 ? void 0 : _a[packageName]) !== undefined ||
+                ((_b = parsed.data.devDependencies) === null || _b === void 0 ? void 0 : _b[packageName]) !== undefined);
+        }
+        catch (_d) {
+            return false;
+        }
+    });
+}
+function detectProjectPackageManager(projectDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const exists = (file) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield stat(join(projectDir, file));
+                return true;
+            }
+            catch (_a) {
+                return false;
+            }
+        });
+        if (yield exists("pnpm-lock.yaml")) {
+            return "pnpm";
+        }
+        if (yield exists("yarn.lock")) {
+            return "yarn";
+        }
+        if ((yield exists("bun.lock")) || (yield exists("bun.lockb"))) {
+            return "bun";
+        }
+        return "npm";
+    });
+}
+/** `agentkit update` — upgrade this install to the latest published version. */
+export function cmdUpdate(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
+        const c = stderrPalette();
+        const out = (_a = options === null || options === void 0 ? void 0 : options.out) !== null && _a !== void 0 ? _a : ((text) => void process.stdout.write(text));
+        const err = (_b = options === null || options === void 0 ? void 0 : options.err) !== null && _b !== void 0 ? _b : ((text) => void process.stderr.write(text));
+        const compiled = (_c = options === null || options === void 0 ? void 0 : options.compiled) !== null && _c !== void 0 ? _c : isCompiledDistribution();
+        if (!compiled) {
+            err(`${CLI_COMMAND_NAME} is running from a source checkout, not an installed package; update it with git instead.\n`);
+            return 1;
+        }
+        const currentVersion = (_d = options === null || options === void 0 ? void 0 : options.currentVersion) !== null && _d !== void 0 ? _d : packageVersion();
+        const latestVersion = yield fetchLatestPublishedVersion({
+            fetchImpl: options === null || options === void 0 ? void 0 : options.fetchImpl,
+            timeoutMs: UPDATE_FETCH_TIMEOUT_MS,
+        });
+        if (latestVersion === undefined) {
+            err(`Could not reach the npm registry to look up the latest ${PACKAGE_NAME} version. Check your network and retry.\n`);
+            return 1;
+        }
+        if (compareVersions(currentVersion, latestVersion) >= 0) {
+            out(`${CLI_COMMAND_NAME} ${currentVersion} is already the latest version.\n`);
+            yield writeUpdateCheckCache({ checkedAt: Date.now(), latestVersion }, options === null || options === void 0 ? void 0 : options.configDir);
+            return 0;
+        }
+        const command = yield detectUpdateCommand({
+            packageRoot: (_e = options === null || options === void 0 ? void 0 : options.packageRoot) !== null && _e !== void 0 ? _e : packageRootDir(),
+        });
+        if (command === undefined) {
+            err(`${CLI_COMMAND_NAME} ${currentVersion} is outdated (latest is ${latestVersion}), but this install's layout was not recognized.\nUpgrade it yourself, e.g. \`npm install -g ${PACKAGE_NAME}@latest\` for a global install, or bump the ${PACKAGE_NAME} dependency in your project.\n`);
+            return 1;
+        }
+        const rendered = [command.cmd, ...command.args].join(" ");
+        err(c.dim(`Updating ${CLI_COMMAND_NAME} ${currentVersion} → ${latestVersion} (${command.reason}):\n  ${rendered}\n`));
+        const run = (_f = options === null || options === void 0 ? void 0 : options.runCommand) !== null && _f !== void 0 ? _f : runUpdateCommand;
+        let code;
+        try {
+            code = yield run(command);
+        }
+        catch (error) {
+            err(`\`${rendered}\` failed: ${describeError(error)}\n`);
+            return 1;
+        }
+        if (code !== 0) {
+            err(`\`${rendered}\` exited with code ${code}.\n`);
+            return code;
+        }
+        yield writeUpdateCheckCache({ checkedAt: Date.now(), latestVersion }, options === null || options === void 0 ? void 0 : options.configDir);
+        out(`Updated ${CLI_COMMAND_NAME} to ${latestVersion}. New commands run the new version.\n`);
+        return 0;
+    });
+}
+function runUpdateCommand(command) {
+    return new Promise((resolve, reject) => {
+        // Windows-only shell: npm/pnpm/yarn/bun are .cmd shims there, and Node
+        // refuses to spawn .cmd files without a shell (EINVAL, CVE-2024-27980
+        // hardening). Injection-safe: cmd and args are module-level constants
+        // from detectUpdateCommand (never user or registry input).
+        // nosemgrep: javascript.lang.security.audit.spawn-shell-true.spawn-shell-true
+        const child = spawn(command.cmd, command.args, {
+            stdio: "inherit",
+            cwd: command.cwd,
+            shell: process.platform === "win32",
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve(code !== null && code !== void 0 ? code : 1);
+        });
+    });
+}

package/dist/internal/workspace.d.ts

@@ -18,6 +18,17 @@ export interface MaterializeWorkspaceOptions {
 }
 /** Relative path of an agent-side tool script inside the session workspace. */
 export declare function agentToolScriptPath(toolName: string): string;
+/**
+ * Always-on identity line prepended when composing instructions. Sourced from
+ * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
+ * so agents know who they are without restating it in authored prose.
+ */
+export declare function buildIdentityPreamble(name: string): string;
+/**
+ * Prepend {@link buildIdentityPreamble} to authored instructions. Used when
+ * loading `instructions.md` / `.ts` / dir into {@link ResolvedAgent.instructions}.
+ */
+export declare function withIdentityPreamble(name: string, instructions: string | undefined): string | undefined;
 /**
  * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAmCf;AAmDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAqCf;AAmDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/internal/workspace.js

@@ -18,10 +18,42 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+import { buildIdentitySection } from "./prompt-context.js";
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName) {
     return `.agent-serve/tools/${toolName}.sh`;
 }
+/**
+ * Always-on identity line prepended when composing instructions. Sourced from
+ * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
+ * so agents know who they are without restating it in authored prose.
+ */
+export function buildIdentityPreamble(name) {
+    const trimmed = name.trim();
+    if (trimmed === "") {
+        return "";
+    }
+    return `You are ${trimmed}. That is your name; use it when people ask who you are.`;
+}
+/**
+ * Prepend {@link buildIdentityPreamble} to authored instructions. Used when
+ * loading `instructions.md` / `.ts` / dir into {@link ResolvedAgent.instructions}.
+ */
+export function withIdentityPreamble(name, instructions) {
+    var _a;
+    const preamble = buildIdentityPreamble(name);
+    const body = (_a = instructions === null || instructions === void 0 ? void 0 : instructions.trim()) !== null && _a !== void 0 ? _a : "";
+    if (preamble === "" && body === "") {
+        return undefined;
+    }
+    if (preamble === "") {
+        return body === "" ? undefined : body;
+    }
+    if (body === "") {
+        return preamble;
+    }
+    return `${preamble}\n\n${body}`;
+}
 /**
  * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
  *
@@ -80,12 +112,14 @@ export function materializeWorkspace(options) {
         const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
             includeScripts: false,
         });
-        const agentsMd = [(_b = (_a = agent.instructions) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "", agentToolsSection]
+        const agentsMd = [
+            (_b = (_a = agent.instructions) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "",
+            buildIdentitySection(agent),
+            agentToolsSection,
+        ]
             .filter((part) => part !== "")
             .join("\n\n");
-        if (agentsMd !== "") {
-            yield writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
-        }
+        yield writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
         for (const tool of agent.tools) {
             if (tool.execution !== "agent" || tool.script === undefined) {
                 continue;