@code-yeongyu/senpi 2026.8.9 → 2026.8.11-2

package/dist/core/brand.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Brand profile resolution.
+ *
+ * A distribution that repackages this engine (for example the `omo-ai` package) injects a
+ * single JSON environment variable describing how the product presents itself. The engine
+ * parses it once at startup and then REMOVES it from the environment, so nested processes
+ * spawned by tools inherit a clean environment and keep the engine's own identity.
+ *
+ * Absent or malformed input leaves every brand-derived value at its standalone default, so a
+ * plain install behaves exactly as it did before this module existed.
+ */
+/** Environment variable carrying the JSON brand profile. */
+export declare const BRAND_ENV_VAR = "SENPI_BRAND";
+/**
+ * Where a repackaging distribution publishes itself. Without this the engine keeps checking
+ * its own package, which would advertise an update the branded product cannot install.
+ */
+export interface BrandUpdateChannel {
+    /** Registry package that ships the branded product, e.g. `omo-ai`. */
+    readonly packageName: string;
+    /** Dist-tag the product publishes on, e.g. `beta`. */
+    readonly distTag: string;
+    /** Command shown to the user, e.g. `npm i -g omo-ai@beta`. */
+    readonly command: string;
+    /** Release notes URL; `{version}` is replaced with the available version. */
+    readonly changelogUrl?: string;
+}
+export interface BrandProfile {
+    /** Product name shown to users and to the model. */
+    readonly name: string;
+    /** Version shown in the header, terminal titles and `--version`. */
+    readonly displayVersion?: string;
+    /** Config directory name, e.g. `.omo`. */
+    readonly configDir: string;
+    /** When true the agent state lives directly under the config directory, with no `agent` segment. */
+    readonly flatLayout: boolean;
+    /** Prefix for the product's environment variables, e.g. `OMO`. */
+    readonly envPrefix: string;
+    /** Product token used in the outgoing user agent. */
+    readonly userAgent: string;
+    /** Product token used as the provider-side originator, when the distribution overrides it. */
+    readonly originator?: string;
+    /** Update channel of the branded product; absent means the product manages updates itself. */
+    readonly update?: BrandUpdateChannel;
+}
+/**
+ * Parses a brand profile. Returns undefined for absent, malformed, or nameless input; a
+ * malformed profile is reported once on stderr and never throws, because a broken brand
+ * must not stop the agent from starting.
+ */
+export declare function parseBrandProfile(raw: string | undefined): BrandProfile | undefined;
+/**
+ * Parses the brand profile without touching the environment.
+ *
+ * The CLI entrypoint re-spawns the real agent as a child process and hands it `process.env`,
+ * so the variable has to survive that hop. Scrubbing therefore happens explicitly in the
+ * process that actually runs the agent - see `scrubBrandFromEnvironment`.
+ */
+export declare function consumeBrandProfile(env?: NodeJS.ProcessEnv): BrandProfile | undefined;
+/**
+ * Removes the brand variable so tools spawning the engine again inherit a clean environment
+ * and keep the engine's own identity. Called once the profile has been resolved by the
+ * process that runs the agent loop.
+ */
+export declare function scrubBrandFromEnvironment(env?: NodeJS.ProcessEnv): void;
+/**
+ * The active brand profile, resolved (and scrubbed from the environment) on first use.
+ */
+export declare function brandProfile(): BrandProfile | undefined;
+/** exported for tests only */
+export declare function resetBrandProfileForTests(): void;
+/** Environment variable names for one setting, most specific first. */
+export declare function brandEnvNames(suffix: string, profile?: BrandProfile | undefined): string[];
+/**
+ * Reads one setting across the brand's prefix and the legacy prefixes, returning the first
+ * DEFINED value so that an explicitly empty value keeps its existing meaning.
+ */
+export declare function envValue(suffix: string, env?: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=brand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/core/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAiCD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAuCnF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,SAAS,CAElG;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAEpF;AAWD;;GAEG;AACH,wBAAgB,YAAY,IAAI,YAAY,GAAG,SAAS,CAMvD;AAED,8BAA8B;AAC9B,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,2BAAiB,GAAG,MAAM,EAAE,CAKhF;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAMjG"}

package/dist/core/brand.js

@@ -0,0 +1,141 @@
+/**
+ * Brand profile resolution.
+ *
+ * A distribution that repackages this engine (for example the `omo-ai` package) injects a
+ * single JSON environment variable describing how the product presents itself. The engine
+ * parses it once at startup and then REMOVES it from the environment, so nested processes
+ * spawned by tools inherit a clean environment and keep the engine's own identity.
+ *
+ * Absent or malformed input leaves every brand-derived value at its standalone default, so a
+ * plain install behaves exactly as it did before this module existed.
+ */
+/** Environment variable carrying the JSON brand profile. */
+export const BRAND_ENV_VAR = "SENPI_BRAND";
+function readUpdateChannel(source) {
+    const update = source.update;
+    if (typeof update !== "object" || update === null || Array.isArray(update))
+        return undefined;
+    const channel = update;
+    const packageName = readString(channel, "packageName");
+    const command = readString(channel, "command");
+    if (!packageName || !command)
+        return undefined;
+    return {
+        packageName,
+        distTag: readString(channel, "distTag") || "latest",
+        command,
+        changelogUrl: readString(channel, "changelogUrl"),
+    };
+}
+/**
+ * A config directory names ONE entry inside the home directory. Anything carrying a separator or
+ * a parent reference would move agent state - and the migration that copies into it - somewhere
+ * the user never agreed to, so such a profile is rejected rather than sanitised.
+ */
+function isSafeConfigDirName(value) {
+    return value !== "." && value !== ".." && !/[\\/]/.test(value);
+}
+function readString(source, key) {
+    const value = source[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/**
+ * Parses a brand profile. Returns undefined for absent, malformed, or nameless input; a
+ * malformed profile is reported once on stderr and never throws, because a broken brand
+ * must not stop the agent from starting.
+ */
+export function parseBrandProfile(raw) {
+    if (!raw?.trim())
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        process.stderr.write(`warning: ignoring malformed ${BRAND_ENV_VAR} (expected JSON)\n`);
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        process.stderr.write(`warning: ignoring malformed ${BRAND_ENV_VAR} (expected a JSON object)\n`);
+        return undefined;
+    }
+    const source = parsed;
+    const name = readString(source, "name");
+    if (!name) {
+        process.stderr.write(`warning: ignoring ${BRAND_ENV_VAR} without a "name"\n`);
+        return undefined;
+    }
+    const configDir = readString(source, "configDir") || `.${name}`;
+    if (!isSafeConfigDirName(configDir)) {
+        process.stderr.write(`warning: ignoring ${BRAND_ENV_VAR} with an unsafe "configDir"\n`);
+        return undefined;
+    }
+    return {
+        name,
+        displayVersion: readString(source, "displayVersion"),
+        configDir,
+        flatLayout: source.flatLayout === true,
+        envPrefix: (readString(source, "envPrefix") || name).toUpperCase(),
+        userAgent: readString(source, "userAgent") || name,
+        originator: readString(source, "originator"),
+        update: readUpdateChannel(source),
+    };
+}
+/**
+ * Parses the brand profile without touching the environment.
+ *
+ * The CLI entrypoint re-spawns the real agent as a child process and hands it `process.env`,
+ * so the variable has to survive that hop. Scrubbing therefore happens explicitly in the
+ * process that actually runs the agent - see `scrubBrandFromEnvironment`.
+ */
+export function consumeBrandProfile(env = process.env) {
+    return parseBrandProfile(env[BRAND_ENV_VAR]);
+}
+/**
+ * Removes the brand variable so tools spawning the engine again inherit a clean environment
+ * and keep the engine's own identity. Called once the profile has been resolved by the
+ * process that runs the agent loop.
+ */
+export function scrubBrandFromEnvironment(env = process.env) {
+    delete env[BRAND_ENV_VAR];
+}
+/**
+ * Environment prefixes read after the brand's own prefix, so a machine configured before the
+ * rebrand keeps working unchanged.
+ */
+const LEGACY_ENV_PREFIXES = ["SENPI", "PI"];
+let cachedProfile;
+let profileResolved = false;
+/**
+ * The active brand profile, resolved (and scrubbed from the environment) on first use.
+ */
+export function brandProfile() {
+    if (!profileResolved) {
+        cachedProfile = consumeBrandProfile();
+        profileResolved = true;
+    }
+    return cachedProfile;
+}
+/** exported for tests only */
+export function resetBrandProfileForTests() {
+    cachedProfile = undefined;
+    profileResolved = false;
+}
+/** Environment variable names for one setting, most specific first. */
+export function brandEnvNames(suffix, profile = brandProfile()) {
+    const prefixes = [profile?.envPrefix, ...LEGACY_ENV_PREFIXES].filter((prefix) => typeof prefix === "string" && prefix.length > 0);
+    return [...new Set(prefixes)].map((prefix) => `${prefix}_${suffix}`);
+}
+/**
+ * Reads one setting across the brand's prefix and the legacy prefixes, returning the first
+ * DEFINED value so that an explicitly empty value keeps its existing meaning.
+ */
+export function envValue(suffix, env = process.env) {
+    for (const name of brandEnvNames(suffix)) {
+        const value = env[name];
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=brand.js.map

package/dist/core/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/core/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAoC3C,SAAS,iBAAiB,CAAC,MAA+B;IACzD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7F,MAAM,OAAO,GAAG,MAAiC,CAAC;IAClD,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC,WAAW,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/C,OAAO;QACN,WAAW;QACX,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,QAAQ;QACnD,OAAO;QACP,YAAY,EAAE,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC;KACjD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,KAAa;IACzC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,UAAU,CAAC,MAA+B,EAAE,GAAW;IAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACxD,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IAEnC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,aAAa,oBAAoB,CAAC,CAAC;QACvF,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,aAAa,6BAA6B,CAAC,CAAC;QAChG,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,aAAa,qBAAqB,CAAC,CAAC;QAC9E,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;IAChE,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,aAAa,+BAA+B,CAAC,CAAC;QACxF,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,OAAO;QACN,IAAI;QACJ,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,gBAAgB,CAAC;QACpD,SAAS;QACT,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,IAAI;QACtC,SAAS,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,EAAE;QAClE,SAAS,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,IAAI;QAClD,UAAU,EAAE,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC;QAC5C,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC;KACjC,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IACvE,OAAO,iBAAiB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC7E,OAAO,GAAG,CAAC,aAAa,CAAC,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,IAAI,CAAU,CAAC;AAErD,IAAI,aAAuC,CAAC;AAC5C,IAAI,eAAe,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,UAAU,YAAY;IAC3B,IAAI,CAAC,eAAe,EAAE,CAAC;QACtB,aAAa,GAAG,mBAAmB,EAAE,CAAC;QACtC,eAAe,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,aAAa,CAAC;AACtB,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,yBAAyB;IACxC,aAAa,GAAG,SAAS,CAAC;IAC1B,eAAe,GAAG,KAAK,CAAC;AACzB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,OAAO,GAAG,YAAY,EAAE;IACrE,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAAC,CAAC,MAAM,CACnE,CAAC,MAAM,EAAoB,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAC7E,CAAC;IACF,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC5E,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IACvC,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Brand profile resolution.\n *\n * A distribution that repackages this engine (for example the `omo-ai` package) injects a\n * single JSON environment variable describing how the product presents itself. The engine\n * parses it once at startup and then REMOVES it from the environment, so nested processes\n * spawned by tools inherit a clean environment and keep the engine's own identity.\n *\n * Absent or malformed input leaves every brand-derived value at its standalone default, so a\n * plain install behaves exactly as it did before this module existed.\n */\n\n/** Environment variable carrying the JSON brand profile. */\nexport const BRAND_ENV_VAR = \"SENPI_BRAND\";\n\n/**\n * Where a repackaging distribution publishes itself. Without this the engine keeps checking\n * its own package, which would advertise an update the branded product cannot install.\n */\nexport interface BrandUpdateChannel {\n\t/** Registry package that ships the branded product, e.g. `omo-ai`. */\n\treadonly packageName: string;\n\t/** Dist-tag the product publishes on, e.g. `beta`. */\n\treadonly distTag: string;\n\t/** Command shown to the user, e.g. `npm i -g omo-ai@beta`. */\n\treadonly command: string;\n\t/** Release notes URL; `{version}` is replaced with the available version. */\n\treadonly changelogUrl?: string;\n}\n\nexport interface BrandProfile {\n\t/** Product name shown to users and to the model. */\n\treadonly name: string;\n\t/** Version shown in the header, terminal titles and `--version`. */\n\treadonly displayVersion?: string;\n\t/** Config directory name, e.g. `.omo`. */\n\treadonly configDir: string;\n\t/** When true the agent state lives directly under the config directory, with no `agent` segment. */\n\treadonly flatLayout: boolean;\n\t/** Prefix for the product's environment variables, e.g. `OMO`. */\n\treadonly envPrefix: string;\n\t/** Product token used in the outgoing user agent. */\n\treadonly userAgent: string;\n\t/** Product token used as the provider-side originator, when the distribution overrides it. */\n\treadonly originator?: string;\n\t/** Update channel of the branded product; absent means the product manages updates itself. */\n\treadonly update?: BrandUpdateChannel;\n}\n\nfunction readUpdateChannel(source: Record<string, unknown>): BrandUpdateChannel | undefined {\n\tconst update = source.update;\n\tif (typeof update !== \"object\" || update === null || Array.isArray(update)) return undefined;\n\n\tconst channel = update as Record<string, unknown>;\n\tconst packageName = readString(channel, \"packageName\");\n\tconst command = readString(channel, \"command\");\n\tif (!packageName || !command) return undefined;\n\n\treturn {\n\t\tpackageName,\n\t\tdistTag: readString(channel, \"distTag\") || \"latest\",\n\t\tcommand,\n\t\tchangelogUrl: readString(channel, \"changelogUrl\"),\n\t};\n}\n\n/**\n * A config directory names ONE entry inside the home directory. Anything carrying a separator or\n * a parent reference would move agent state - and the migration that copies into it - somewhere\n * the user never agreed to, so such a profile is rejected rather than sanitised.\n */\nfunction isSafeConfigDirName(value: string): boolean {\n\treturn value !== \".\" && value !== \"..\" && !/[\\\\/]/.test(value);\n}\n\nfunction readString(source: Record<string, unknown>, key: string): string | undefined {\n\tconst value = source[key];\n\treturn typeof value === \"string\" && value.trim() ? value.trim() : undefined;\n}\n\n/**\n * Parses a brand profile. Returns undefined for absent, malformed, or nameless input; a\n * malformed profile is reported once on stderr and never throws, because a broken brand\n * must not stop the agent from starting.\n */\nexport function parseBrandProfile(raw: string | undefined): BrandProfile | undefined {\n\tif (!raw?.trim()) return undefined;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch {\n\t\tprocess.stderr.write(`warning: ignoring malformed ${BRAND_ENV_VAR} (expected JSON)\\n`);\n\t\treturn undefined;\n\t}\n\n\tif (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n\t\tprocess.stderr.write(`warning: ignoring malformed ${BRAND_ENV_VAR} (expected a JSON object)\\n`);\n\t\treturn undefined;\n\t}\n\n\tconst source = parsed as Record<string, unknown>;\n\tconst name = readString(source, \"name\");\n\tif (!name) {\n\t\tprocess.stderr.write(`warning: ignoring ${BRAND_ENV_VAR} without a \"name\"\\n`);\n\t\treturn undefined;\n\t}\n\n\tconst configDir = readString(source, \"configDir\") || `.${name}`;\n\tif (!isSafeConfigDirName(configDir)) {\n\t\tprocess.stderr.write(`warning: ignoring ${BRAND_ENV_VAR} with an unsafe \"configDir\"\\n`);\n\t\treturn undefined;\n\t}\n\n\treturn {\n\t\tname,\n\t\tdisplayVersion: readString(source, \"displayVersion\"),\n\t\tconfigDir,\n\t\tflatLayout: source.flatLayout === true,\n\t\tenvPrefix: (readString(source, \"envPrefix\") || name).toUpperCase(),\n\t\tuserAgent: readString(source, \"userAgent\") || name,\n\t\toriginator: readString(source, \"originator\"),\n\t\tupdate: readUpdateChannel(source),\n\t};\n}\n\n/**\n * Parses the brand profile without touching the environment.\n *\n * The CLI entrypoint re-spawns the real agent as a child process and hands it `process.env`,\n * so the variable has to survive that hop. Scrubbing therefore happens explicitly in the\n * process that actually runs the agent - see `scrubBrandFromEnvironment`.\n */\nexport function consumeBrandProfile(env: NodeJS.ProcessEnv = process.env): BrandProfile | undefined {\n\treturn parseBrandProfile(env[BRAND_ENV_VAR]);\n}\n\n/**\n * Removes the brand variable so tools spawning the engine again inherit a clean environment\n * and keep the engine's own identity. Called once the profile has been resolved by the\n * process that runs the agent loop.\n */\nexport function scrubBrandFromEnvironment(env: NodeJS.ProcessEnv = process.env): void {\n\tdelete env[BRAND_ENV_VAR];\n}\n\n/**\n * Environment prefixes read after the brand's own prefix, so a machine configured before the\n * rebrand keeps working unchanged.\n */\nconst LEGACY_ENV_PREFIXES = [\"SENPI\", \"PI\"] as const;\n\nlet cachedProfile: BrandProfile | undefined;\nlet profileResolved = false;\n\n/**\n * The active brand profile, resolved (and scrubbed from the environment) on first use.\n */\nexport function brandProfile(): BrandProfile | undefined {\n\tif (!profileResolved) {\n\t\tcachedProfile = consumeBrandProfile();\n\t\tprofileResolved = true;\n\t}\n\treturn cachedProfile;\n}\n\n/** exported for tests only */\nexport function resetBrandProfileForTests(): void {\n\tcachedProfile = undefined;\n\tprofileResolved = false;\n}\n\n/** Environment variable names for one setting, most specific first. */\nexport function brandEnvNames(suffix: string, profile = brandProfile()): string[] {\n\tconst prefixes = [profile?.envPrefix, ...LEGACY_ENV_PREFIXES].filter(\n\t\t(prefix): prefix is string => typeof prefix === \"string\" && prefix.length > 0,\n\t);\n\treturn [...new Set(prefixes)].map((prefix) => `${prefix}_${suffix}`);\n}\n\n/**\n * Reads one setting across the brand's prefix and the legacy prefixes, returning the first\n * DEFINED value so that an explicitly empty value keeps its existing meaning.\n */\nexport function envValue(suffix: string, env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tfor (const name of brandEnvNames(suffix)) {\n\t\tconst value = env[name];\n\t\tif (value !== undefined) return value;\n\t}\n\treturn undefined;\n}\n"]}

package/dist/core/dynamic-prompt/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/core/dynamic-prompt/identity.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/core/dynamic-prompt/identity.ts"],"names":[],"mappings":"AAEA,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/core/dynamic-prompt/identity.js

@@ -1,4 +1,5 @@
+import { APP_NAME } from "../../config.js";
 export function buildIdentitySection() {
-    return "You are senpi, a coding agent. Your work should be indistinguishable from a careful senior engineer's.";
+    return `You are ${APP_NAME}, a coding agent. Your work should be indistinguishable from a careful senior engineer's.`;
 }
 //# sourceMappingURL=identity.js.map

package/dist/core/dynamic-prompt/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/core/dynamic-prompt/identity.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB;IACnC,OAAO,wGAAwG,CAAC;AACjH,CAAC","sourcesContent":["export function buildIdentitySection(): string {\n\treturn \"You are senpi, a coding agent. Your work should be indistinguishable from a careful senior engineer's.\";\n}\n"]}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/core/dynamic-prompt/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,MAAM,UAAU,oBAAoB;IACnC,OAAO,WAAW,QAAQ,2FAA2F,CAAC;AACvH,CAAC","sourcesContent":["import { APP_NAME } from \"../../config.ts\";\n\nexport function buildIdentitySection(): string {\n\treturn `You are ${APP_NAME}, a coding agent. Your work should be indistinguishable from a careful senior engineer's.`;\n}\n"]}

package/dist/core/experimental.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"experimental.d.ts","sourceRoot":"","sources":["../../src/core/experimental.ts"],"names":[],"mappings":"AAAA,wBAAgB,8BAA8B,IAAI,OAAO,CAExD"}
+{"version":3,"file":"experimental.d.ts","sourceRoot":"","sources":["../../src/core/experimental.ts"],"names":[],"mappings":"AACA,wBAAgB,8BAA8B,IAAI,OAAO,CAExD"}

package/dist/core/experimental.js

@@ -1,4 +1,5 @@
+import { envValue } from "./brand.js";
 export function areExperimentalFeaturesEnabled() {
-    return process.env.PI_EXPERIMENTAL === "1";
+    return envValue("EXPERIMENTAL") === "1";
 }
 //# sourceMappingURL=experimental.js.map

package/dist/core/experimental.js.map

@@ -1 +1 @@
-{"version":3,"file":"experimental.js","sourceRoot":"","sources":["../../src/core/experimental.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,8BAA8B;IAC7C,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC;AAC5C,CAAC","sourcesContent":["export function areExperimentalFeaturesEnabled(): boolean {\n\treturn process.env.PI_EXPERIMENTAL === \"1\";\n}\n"]}
+{"version":3,"file":"experimental.js","sourceRoot":"","sources":["../../src/core/experimental.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,MAAM,UAAU,8BAA8B;IAC7C,OAAO,QAAQ,CAAC,cAAc,CAAC,KAAK,GAAG,CAAC;AACzC,CAAC","sourcesContent":["import { envValue } from \"./brand.ts\";\nexport function areExperimentalFeaturesEnabled(): boolean {\n\treturn envValue(\"EXPERIMENTAL\") === \"1\";\n}\n"]}

package/dist/core/extensions/builtin/cache-keepalive/index.d.ts

@@ -0,0 +1,30 @@
+import { type Context, type Model, type WarmPromptCacheOptions, type WarmPromptCacheResult } from "@earendil-works/pi-ai";
+import type { EntryRenderer, ExtensionFactory } from "../../types.ts";
+export declare const CACHE_KEEPALIVE_ENTRY_TYPE = "cache-keepalive";
+export declare const CACHE_WARM_PING_EVENT = "cache_warm_ping";
+interface StartedEntry {
+    readonly phase: "started";
+}
+interface PingEntry {
+    readonly phase: "ping";
+    readonly iteration: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly estimatedCostUsd: number;
+    readonly cumulativeEstimatedUsd: number;
+}
+interface StoppedEntry {
+    readonly phase: "stopped";
+    readonly iterations: number;
+    readonly stopReason: string;
+    readonly cumulativeEstimatedUsd: number;
+}
+export type CacheKeepAliveEntryData = StartedEntry | PingEntry | StoppedEntry;
+type WarmPromptCacheFn = (model: Model<any>, context: Context, options?: WarmPromptCacheOptions) => Promise<WarmPromptCacheResult>;
+export declare const renderCacheKeepAliveEntry: EntryRenderer<CacheKeepAliveEntryData>;
+export declare function createCacheKeepAliveExtension(dependencies?: {
+    readonly warmPromptCache?: WarmPromptCacheFn;
+}): ExtensionFactory;
+declare const _default: ExtensionFactory;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/extensions/builtin/cache-keepalive/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/cache-keepalive/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,KAAK,EAGV,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAE1B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,aAAa,EAAkC,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAItG,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAC5D,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,UAAU,YAAY;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC1B;AAED,UAAU,SAAS;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACxC;AAED,UAAU,YAAY;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,SAAS,GAAG,YAAY,CAAC;AAE9E,KAAK,iBAAiB,GAAG,CACxB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,sBAAsB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAEpC,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,uBAAuB,CAS3E,CAAC;AAEH,wBAAgB,6BAA6B,CAC5C,YAAY,GAAE;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAA;CAAO,GACjE,gBAAgB,CAwNlB"}

package/dist/core/extensions/builtin/cache-keepalive/index.js

@@ -0,0 +1,281 @@
+import { isAnthropicApiBaseUrl, resolvePromptCacheTtlSeconds, warmPromptCache, } from "@earendil-works/pi-ai";
+import { convertToLlm, filterContextExcludedMessages } from "../../../messages.js";
+import { noticeEntryRenderer } from "../../notice/index.js";
+import { formatWarmTokenCount } from "../goal/cache-warm.js";
+import { GOAL_CONTINUATION_TIMER_STATE_EVENT } from "../goal/monitor-continuation.js";
+export const CACHE_KEEPALIVE_ENTRY_TYPE = "cache-keepalive";
+export const CACHE_WARM_PING_EVENT = "cache_warm_ping";
+export const renderCacheKeepAliveEntry = noticeEntryRenderer((entry) => {
+    const data = entry.data;
+    if (data?.phase !== "ping")
+        return undefined;
+    const refreshed = data.cacheRead + data.cacheWrite;
+    return {
+        title: `⚡ Warm ping #${data.iteration} · ~${formatWarmTokenCount(refreshed)} tokens refreshed · ${formatUsd(data.estimatedCostUsd)}`,
+        why: "Refreshed the active Anthropic prompt cache while the session was idle.",
+        expandedLine: `cache read ${data.cacheRead} · cache write ${data.cacheWrite} · session total ${formatUsd(data.cumulativeEstimatedUsd)}`,
+    };
+});
+export function createCacheKeepAliveExtension(dependencies = {}) {
+    const warm = dependencies.warmPromptCache ?? warmPromptCache;
+    return (pi) => {
+        let ctx;
+        let timer;
+        let inFlight = false;
+        let generation = 0;
+        let active = false;
+        let goalTimerArmed = false;
+        let attempts = 0;
+        let cumulativeEstimatedUsd = 0;
+        let lastCompletedAtMs;
+        let lastMessages = [];
+        let lastUsage;
+        pi.registerEntryRenderer(CACHE_KEEPALIVE_ENTRY_TYPE, renderCacheKeepAliveEntry);
+        const unsubscribeGoalTimer = pi.events?.on(GOAL_CONTINUATION_TIMER_STATE_EVENT, (data) => {
+            if (!isGoalTimerState(data))
+                return;
+            goalTimerArmed = data.armed;
+            if (data.armed)
+                stop("goal-timer-armed");
+        });
+        function append(data) {
+            pi.appendEntry(CACHE_KEEPALIVE_ENTRY_TYPE, data);
+        }
+        function stop(reason, forceEntry = false) {
+            const shouldAppend = active || inFlight || timer !== undefined || forceEntry;
+            generation += 1;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            active = false;
+            if (shouldAppend) {
+                append({
+                    phase: "stopped",
+                    iterations: attempts,
+                    stopReason: reason,
+                    cumulativeEstimatedUsd,
+                });
+            }
+        }
+        function arm() {
+            if (timer !== undefined || inFlight)
+                return;
+            const current = ctx;
+            const settings = current?.getPromptCacheKeepAliveSettings?.();
+            if (!settings?.enabled || current?.model === undefined || lastCompletedAtMs === undefined)
+                return;
+            if (!isWarmSupportedModel(current.model))
+                return;
+            if (!current.isIdle()) {
+                stop("agent-busy");
+                return;
+            }
+            if (current.hasPendingMessages()) {
+                stop("pending-messages");
+                return;
+            }
+            if (goalTimerArmed) {
+                stop("goal-timer-armed");
+                return;
+            }
+            const safeWaitSeconds = current.getPromptCacheSafeWaitSeconds?.();
+            if (safeWaitSeconds === undefined || !Number.isFinite(safeWaitSeconds))
+                return;
+            if (attempts >= Math.max(0, settings.maxRequestsPerSession)) {
+                stop("max-requests", true);
+                return;
+            }
+            const projectedUsd = projectedPingCost(current.model, lastUsage);
+            if (cumulativeEstimatedUsd + projectedUsd > Math.max(0, settings.maxCostUsdPerSession)) {
+                stop("cost-cap", true);
+                return;
+            }
+            if (!active) {
+                active = true;
+                append({ phase: "started" });
+            }
+            const intervalMs = Math.max(0, safeWaitSeconds - Math.max(0, settings.marginSeconds)) * 1000;
+            const delayMs = Math.max(0, lastCompletedAtMs + intervalMs - Date.now());
+            const scheduledGeneration = generation;
+            timer = setTimeout(() => {
+                timer = undefined;
+                void ping(scheduledGeneration);
+            }, delayMs);
+        }
+        async function ping(scheduledGeneration) {
+            if (scheduledGeneration !== generation)
+                return;
+            const current = ctx;
+            const settings = current?.getPromptCacheKeepAliveSettings?.();
+            if (current === undefined ||
+                settings?.enabled !== true ||
+                current.model === undefined ||
+                !isWarmSupportedModel(current.model) ||
+                !current.isIdle() ||
+                current.hasPendingMessages() ||
+                goalTimerArmed ||
+                attempts >= Math.max(0, settings.maxRequestsPerSession) ||
+                cumulativeEstimatedUsd + projectedPingCost(current.model, lastUsage) >
+                    Math.max(0, settings.maxCostUsdPerSession)) {
+                arm();
+                return;
+            }
+            inFlight = true;
+            attempts += 1;
+            const iteration = attempts;
+            const pingGeneration = generation;
+            try {
+                const preparation = await current.prepareProviderRequest?.(lastMessages);
+                if (pingGeneration !== generation) {
+                    inFlight = false;
+                    arm();
+                    return;
+                }
+                const preparedMessages = preparation?.messages ?? lastMessages;
+                const activeToolNames = new Set(pi.getActiveTools());
+                const tools = pi
+                    .getAllTools()
+                    .filter((tool) => activeToolNames.has(tool.name))
+                    .map(({ name, description, parameters }) => ({ name, description, parameters }));
+                const auth = await current.modelRegistry.getApiKeyAndHeaders(current.model);
+                if (pingGeneration !== generation) {
+                    inFlight = false;
+                    arm();
+                    return;
+                }
+                if (!auth.ok)
+                    throw new Error(auth.error);
+                const authHeaders = auth.headers ?? {};
+                const headers = preparation ? await preparation.transformHeaders(authHeaders) : authHeaders;
+                const result = await warm(current.model, {
+                    systemPrompt: current.getSystemPrompt(),
+                    messages: convertToLlm(filterContextExcludedMessages(preparedMessages)),
+                    ...(tools.length > 0 ? { tools } : {}),
+                }, {
+                    apiKey: auth.apiKey,
+                    headers,
+                    sessionId: current.sessionManager.getSessionId(),
+                    cacheRetention: current.model.cacheRetention,
+                    onPayload: preparation ? async (payload) => await preparation.transformPayload(payload) : undefined,
+                });
+                if (pingGeneration !== generation) {
+                    inFlight = false;
+                    arm();
+                    return;
+                }
+                if (!result.supported) {
+                    inFlight = false;
+                    stop("unsupported-model");
+                    return;
+                }
+                const estimatedCostUsd = actualPingCost(current.model, result.usage);
+                cumulativeEstimatedUsd += estimatedCostUsd;
+                lastCompletedAtMs = Date.now();
+                const cachedTokens = result.usage.cacheRead + result.usage.cacheWrite;
+                const ttlSeconds = resolvePromptCacheTtlSeconds(current.model) ?? 0;
+                pi.events?.emit(CACHE_WARM_PING_EVENT, { iteration, cachedTokens, ttlSeconds, estimatedCostUsd });
+                append({
+                    phase: "ping",
+                    iteration,
+                    cacheRead: result.usage.cacheRead,
+                    cacheWrite: result.usage.cacheWrite,
+                    estimatedCostUsd,
+                    cumulativeEstimatedUsd,
+                });
+                inFlight = false;
+                arm();
+            }
+            catch {
+                inFlight = false;
+                if (pingGeneration === generation)
+                    stop("provider-error");
+                else
+                    arm();
+            }
+        }
+        pi.on("session_start", (_event, nextCtx) => {
+            stop("session-restart");
+            ctx = nextCtx;
+            attempts = 0;
+            cumulativeEstimatedUsd = 0;
+            lastMessages = nextCtx.sessionManager.buildSessionContext().messages;
+            const usage = lastAssistantUsage(lastMessages);
+            lastUsage = usage;
+            lastCompletedAtMs = lastAssistantTimestamp(lastMessages);
+            arm();
+        });
+        pi.on("agent_end", (event, nextCtx) => {
+            ctx = nextCtx;
+            const usage = lastAssistantUsage(event.messages);
+            if (usage?.stopReason === "error") {
+                stop("provider-error");
+                return;
+            }
+            lastMessages = [...event.messages];
+            lastUsage = usage;
+            lastCompletedAtMs = Date.now();
+            arm();
+        });
+        pi.on("model_select", (_event, nextCtx) => {
+            ctx = nextCtx;
+            stop("model-changed");
+            arm();
+        });
+        pi.on("agent_start", () => stop("agent-busy"));
+        pi.on("input", () => stop("user-input"));
+        pi.on("session_shutdown", () => {
+            stop("session-dispose");
+            unsubscribeGoalTimer?.();
+            ctx = undefined;
+        });
+    };
+}
+function isWarmSupportedModel(model) {
+    return model.api === "anthropic-messages" && isAnthropicApiBaseUrl(model.baseUrl);
+}
+function lastAssistantUsage(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role !== "assistant")
+            continue;
+        return {
+            input: finiteTokens(message.usage.input),
+            cacheRead: finiteTokens(message.usage.cacheRead),
+            cacheWrite: finiteTokens(message.usage.cacheWrite),
+            stopReason: message.stopReason,
+        };
+    }
+    return undefined;
+}
+function lastAssistantTimestamp(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === "assistant" && Number.isFinite(message.timestamp))
+            return message.timestamp;
+    }
+    return undefined;
+}
+function projectedPingCost(model, usage) {
+    const promptTokens = (usage?.input ?? 0) + (usage?.cacheRead ?? 0) + (usage?.cacheWrite ?? 0);
+    return (promptTokens * Math.max(model.cost.cacheRead, model.cost.cacheWrite)) / 1_000_000;
+}
+function actualPingCost(model, usage) {
+    return ((usage.cacheRead * model.cost.cacheRead +
+        usage.cacheWrite * model.cost.cacheWrite +
+        usage.input * model.cost.input) /
+        1_000_000);
+}
+function finiteTokens(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+function formatUsd(value) {
+    return `$${value.toFixed(3)}`;
+}
+function isGoalTimerState(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.armed === "boolean" &&
+        typeof value.kind === "string");
+}
+export default createCacheKeepAliveExtension();
+//# sourceMappingURL=index.js.map