@atomic-chat/core 0.20.6 → 0.21.0

package/dist/integrations/configure/goose.js

@@ -1,16 +1,147 @@
 /**
- * Goose reads `GOOSE_PROVIDER` / `GOOSE_MODEL` plus the OpenAI host variables from the environment;
- * there is no provider file to patch. Goose appends its own path, so `OPENAI_HOST` is the bare
- * host:port (the catalog marks it `endpointWithPrefix: false`) and `OPENAI_BASE_PATH` carries the
- * chat-completions path.
+ * Goose — a connection writes nothing. `launch` starts `goose session` with its provider, model,
+ * endpoint, key and window in that one process's environment (`childEnv` in the catalog), so nothing
+ * outside it changes.
  *
- * The block also holds `OPENAI_*` variables, which do not share the `GOOSE_` prefix. Rerun stays
- * idempotent because the whole marked region is removed first; the prefix filter is only the safety
- * net for stray lines outside it, which is why a user's own `export OPENAI_API_KEY` survives.
+ * Earlier releases saved the same variables for the whole user instead — a marked block in the shell
+ * rc file, or `setx` on Windows — which pointed every OpenAI SDK tool on the machine at Atomic Chat
+ * (`OPENAI_API_KEY`, `OPENAI_HOST`). Configuring takes exactly that out again, and nothing a user
+ * wrote. Port of `goose_config.rs` in the app.
  */
+import { AtomicCoreError } from '../../contracts/index.js';
 import { registerWriter } from './registry.js';
-import { configureEnvAgent } from './env-agent.js';
-const MARKER = '# Atomic Chat - Goose Config';
-export const configureGoose = (input) => configureEnvAgent(input, { agentId: 'goose', marker: MARKER, prefix: 'GOOSE_' });
+/** The line that opened and closed the block earlier releases wrote. */
+export const LEGACY_SHELL_MARKER = '# Atomic Chat - Goose Config';
+/** The variables that block (or `setx`) held. */
+const LEGACY_VARS = ['GOOSE_PROVIDER', 'GOOSE_MODEL', 'OPENAI_HOST', 'OPENAI_BASE_PATH', 'OPENAI_API_KEY'];
+const LEGACY_BASE_PATH = 'v1/chat/completions';
+/** The key written when the server had none. */
+const KEY_PLACEHOLDER = 'atomic';
+/** The rc files `shellRcFile` could have picked for the `$SHELL` of the time. */
+const LEGACY_RC_FILES = ['.zshenv', '.bashrc', '.bash_profile'];
+function isLegacyExport(line) {
+    const rest = line.trimStart();
+    if (!rest.startsWith('export '))
+        return false;
+    const eq = rest.indexOf('=');
+    return eq >= 0 && LEGACY_VARS.includes(rest.slice('export '.length, eq).trim());
+}
+/**
+ * `content` without our Goose blocks, or `undefined` when it has none. A block runs from one marker
+ * line to the next; within it only the marker lines, our `export` lines and blank lines go — anything
+ * else a user put there stays. A marker without a partner goes alone.
+ */
+export function stripLegacyGooseBlock(content) {
+    const lines = content.split('\n');
+    const markers = lines.flatMap((line, i) => (line.startsWith(LEGACY_SHELL_MARKER) ? [i] : []));
+    if (markers.length === 0)
+        return undefined;
+    const inBlock = (i) => {
+        for (let p = 0; p + 1 < markers.length; p += 2) {
+            if (markers[p] < i && i < markers[p + 1])
+                return true;
+        }
+        return false;
+    };
+    return lines
+        .filter((line, i) => {
+        if (markers.includes(i))
+            return false;
+        return !(inBlock(i) && (line.trim() === '' || isLegacyExport(line)));
+    })
+        .join('\n');
+}
+/** `localhost`, loopback, unspecified, private or link-local: a host an earlier release pointed at. */
+function isLocalUrl(raw) {
+    let host;
+    try {
+        host = new URL(raw.includes('://') ? raw : `http://${raw}`).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    host = host.replace(/^\[|\]$/g, '');
+    if (host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '::')
+        return true;
+    if (/^f[cd][0-9a-f]{2}:/.test(host) || /^fe[89ab][0-9a-f]:/.test(host))
+        return true;
+    const v4 = host.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (!v4)
+        return false;
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    return (a === 127 ||
+        a === 10 ||
+        a === 0 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254));
+}
+/**
+ * The User-scope variables (`read` looks one up) that are recognisably what an earlier release set
+ * with `setx`: Goose on the OpenAI provider with our fixed base path at a local host. The key goes
+ * only when it is our placeholder or the server's own key.
+ */
+export function legacyGooseUserVars(read, apiKey) {
+    const ours = read('GOOSE_PROVIDER')?.trim() === 'openai' &&
+        read('OPENAI_BASE_PATH')?.trim() === LEGACY_BASE_PATH &&
+        isLocalUrl(read('OPENAI_HOST') ?? '');
+    if (!ours)
+        return [];
+    return LEGACY_VARS.filter((name) => {
+        const value = read(name);
+        if (value === undefined)
+            return false;
+        if (name === 'OPENAI_API_KEY')
+            return value === KEY_PLACEHOLDER || (apiKey !== '' && value === apiKey);
+        return true;
+    });
+}
+/** `reg query HKCU\Environment /v <name>`'s value, `undefined` when there is none. */
+async function readUserVar(spawn, name) {
+    const result = await spawn('reg', ['query', 'HKCU\\Environment', '/v', name]).catch(() => undefined);
+    if (!result || result.code !== 0)
+        return undefined;
+    for (const line of result.stdout.split(/\r?\n/)) {
+        const match = line.match(/^\s+(\S+)\s+REG_\w+\s+(.*)$/);
+        if (match && match[1]?.toLowerCase() === name.toLowerCase()) {
+            // `(.*)` always takes part in a match, so group 2 is a string here.
+            const value = match[2].trim();
+            return value === '' ? undefined : value;
+        }
+    }
+    return undefined;
+}
+export const configureGoose = async (input) => {
+    const { fs } = input;
+    for (const rc of LEGACY_RC_FILES) {
+        const content = await fs.read(rc);
+        if (content === undefined)
+            continue;
+        const cleaned = stripLegacyGooseBlock(content);
+        if (cleaned !== undefined)
+            await fs.write(rc, cleaned);
+    }
+    if (input.platform !== 'win32' || !input.spawn)
+        return;
+    const spawn = input.spawn;
+    const values = new Map();
+    for (const name of LEGACY_VARS) {
+        const value = await readUserVar(spawn, name);
+        if (value !== undefined)
+            values.set(name, value);
+    }
+    const names = legacyGooseUserVars((name) => values.get(name), input.apiKey);
+    if (names.length === 0)
+        return;
+    // `SetEnvironmentVariable(…, $null, 'User')` deletes the value and broadcasts WM_SETTINGCHANGE,
+    // as `setx` did when it set it. The names are our constants.
+    const script = names
+        .map((name) => `[Environment]::SetEnvironmentVariable('${name}', $null, 'User')`)
+        .join('; ');
+    const result = await spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', script]);
+    if (result.code !== 0) {
+        throw new AtomicCoreError('IO_ERROR', `Could not remove the Goose variables an earlier Atomic Chat set: ${result.stderr.trim()}`);
+    }
+};
 registerWriter('goose', configureGoose);
 //# sourceMappingURL=goose.js.map

package/dist/integrations/configure/goose.js.map

@@ -1 +1 @@
-{"version":3,"file":"goose.js","sourceRoot":"","sources":["../../../src/integrations/configure/goose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAElD,MAAM,MAAM,GAAG,8BAA8B,CAAA;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAoB,CAAC,KAAK,EAAE,EAAE,CACvD,iBAAiB,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;AAElF,cAAc,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA"}
+{"version":3,"file":"goose.js","sourceRoot":"","sources":["../../../src/integrations/configure/goose.ts"],"names":[],"mappings":"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"}

package/dist/integrations/configure/hermes.d.ts

@@ -3,17 +3,34 @@
  *
  * That is deliberate: the file is hand-edited, heavily commented, and its `custom_providers` list
  * carries the user's own bridges (Telegram, WhatsApp, …). A YAML round trip would drop every comment
- * and reflow every block for the sake of three scalars. So we rewrite only the lines we own and
+ * and reflow every block for the sake of a few scalars. So we rewrite only the lines we own and
  * splice our list entry in, leaving everything else byte-identical.
  *
- * Hermes ignores the API key entirely (`api_key` is accepted for call-site symmetry and reserved),
- * and `.env` is patched only when it already exists — creating one would shadow the agent's own
- * defaults.
+ * The route is bare `custom` with `model.base_url` and `model.api_key`: Hermes trusts that URL while
+ * `model.provider` is `custom` and takes the key from the same section, so the route needs nothing
+ * outside it — unlike `custom:atomic-chat`, which needs our `custom_providers` entry, and that cannot
+ * be added to an inline `custom_providers: [...]` list. The entry is still written where it can be,
+ * for `hermes model` and detection. What the edit replaced is recorded in
+ * `config.yaml.atomic-chat-backup.json` for the app's Disconnect. `.env` is patched only when it
+ * already exists — creating one would shadow the agent's own defaults.
+ *
+ * Mirrors `configure_hermes_at` in the app's `core/system/commands.rs`, byte for byte.
  */
 import type { ConfigFs } from '../config-io.js';
 import type { ConfigureWriter } from './registry.js';
 /** Rewrite everything after the first colon, with no quoting — the values here never need it. */
 export declare function replaceYamlScalarValue(line: string, value: string): string;
+/**
+ * Point the top-level `model:` section at our endpoint, and touch nothing outside it.
+ *
+ * Hermes' chat route comes from `model.default` (`model.model` is an alias), `model.provider` and
+ * `model.base_url`; a section it cannot read leaves it on its built-in default, an empty model on
+ * provider `auto`, which falls through to OpenRouter. The same keys recur under `auxiliary:`,
+ * `delegation:`, `compression:` and others, so only direct children of the top-level `model:` key are
+ * ours. A missing key is added, a scalar `model: <id>` (also valid Hermes) becomes a block, and a file
+ * with no `model:` at all gets one appended.
+ */
+export declare function patchModelSection(content: string, wanted: Array<[string, string]>): string;
 /**
  * Split the document into (before, entries, after) around `custom_providers:`. `entries` is one
  * array of raw lines per list item; blank lines inside the block are dropped, which is why a rerun
@@ -26,16 +43,52 @@ export declare function splitCustomProviders(content: string): {
 };
 /** Re-emit the block: items at column 0, or `custom_providers: []` when nothing is left. */
 export declare function rebuildCustomProviders(before: string[], entries: string[][], after: string[]): string;
-/** Add or update only our entry, leaving the user's other bridges untouched and in order. */
-export declare function upsertAtomicProvider(content: string, apiUrl: string, model: string, ctx: number): string;
+/**
+ * Add or update only our entry, leaving the user's other bridges untouched and in order; also says
+ * whether the `custom_providers` key itself was added. `key` is already a YAML scalar.
+ */
+export declare function upsertAtomicProvider(content: string, apiUrl: string, model: string, ctx: number, key: string): [string, boolean];
 /**
  * Ensure `providers.<id>.request_timeout_seconds` exists, creating the `providers:` map and the
  * provider sub-block as needed. A value the user already set is left alone — we only fill the gap.
+ * Also returns what it created, for Disconnect: `providers`, `providers:{}` (an empty inline map
+ * turned into a block), `providers.<id>` and `providers.<id>.request_timeout_seconds`.
+ */
+export declare function upsertProviderRequestTimeout(content: string, providerId: string, seconds: number): [string, string[]];
+/** One `model:` key Connect wrote: the lines it replaced (absent: none) and the value it wrote. */
+interface KeyBackup {
+    before?: string[];
+    ours: string;
+}
+/** What Connect changed in `config.yaml` (the app's `HermesBackup`). */
+export interface HermesBackup {
+    /** The `model:` line before Connect; absent when there was no section. */
+    header?: string;
+    keys: Record<string, KeyBackup>;
+    /** What Connect added that was not there at all (see `upsertProviderRequestTimeout`). */
+    created: string[];
+}
+export declare function parseHermesBackup(text: string): HermesBackup | undefined;
+export declare function renderHermesBackup(backup: HermesBackup): string;
+/**
+ * The backup of a Connect that wrote `route` over `content`. A key an earlier Connect recorded keeps
+ * that record's original while it still holds the value that Connect wrote; otherwise the user
+ * changed it since, and the current lines are the ones to return to.
+ */
+export declare function hermesBackup(content: string, route: Array<[string, string]>, previous: HermesBackup | undefined, created: string[]): HermesBackup;
+/**
+ * `HERMES_HOME` as Hermes reads it (`os.path.expanduser(os.path.expandvars(...))`): `$NAME`,
+ * `${NAME}` and `%NAME%` take the variable's value (an unset one stays as written), then a leading
+ * `~` is the user's home.
  */
-export declare function upsertProviderRequestTimeout(content: string, providerId: string, seconds: number): string;
+export declare function expandHermesHome(raw: string, env: NodeJS.ProcessEnv, home: string): string;
 /**
- * `~/.hermes` everywhere except Windows, where the installer writes `HERMES_HOME` to the user
- * environment and the CLI honours it.
+ * The directory whose `config.yaml` the `hermes` CLI reads (`resolve_hermes_dir` in the app):
+ * `HERMES_HOME` (expanded) or the platform default (`%LOCALAPPDATA%/hermes` on Windows, `~/.hermes`
+ * elsewhere) is the root; a `HERMES_HOME` naming a profile (`<root>/profiles/<name>`) is used as it
+ * is; otherwise the sticky profile `hermes profile use <name>` leaves in `<root>/active_profile` is
+ * what every `hermes` without `-p` runs, from `<root>/profiles/<name>`.
  */
-export declare function hermesDir(env: NodeJS.ProcessEnv, platform: NodeJS.Platform, fs: ConfigFs): string;
+export declare function hermesDir(env: NodeJS.ProcessEnv, platform: NodeJS.Platform, fs: ConfigFs): Promise<string>;
 export declare const configureHermes: ConfigureWriter;
+export {};