@skrr-ai/cli 0.1.8

package/dist/lib/sky-code-managed.d.ts

@@ -0,0 +1,179 @@
+/**
+ * OSK-3892 — the DECISION half of a CLI-hosted managed skrr Code session.
+ *
+ * skrr Code is standalone-capable and daemon-preferred: when a daemon is in the
+ * loop it brokers inference, and when a human just ran `skrr login` the CLI hosts
+ * the broker itself. This module answers the two questions that must be answered
+ * BEFORE any credential exists —
+ *
+ *   would this process broker, and if not, why not?
+ *   what does the engine's own argv say about the model, and what must be
+ *   removed from it before the engine sees it?
+ *
+ * — and it answers them from the environment alone.
+ *
+ * ── Why the decision is separated from the acquisition ─────────────────────
+ *
+ * Everything here is pure (env, a config read, one `existsSync`) and imports no
+ * auth, no data-provider and no broker. That is what lets `skrr code doctor` report
+ * the posture without configuring the auth plane, and it keeps
+ * `sky-code-doctor.ts` honest about being safe to run in any context. The
+ * acquisition and the `execEngine` hooks that drive it live in
+ * `sky-code-broker.ts`, which the `skrr code` commands import directly.
+ *
+ * ── Invariant I4: managed / BYOK / offline never silently become each other ─
+ *
+ * So a skip has TWO kinds. A structural one ("a daemon already brokers this",
+ * "the operator turned it off") is expected and silent — announcing it on every
+ * daemon-spawned invocation would be noise nobody reads. A skip that would
+ * otherwise look like a broken feature ("your server is not HTTPS") is announced,
+ * once, on stderr. Acquisition failures are always announced, for the same
+ * reason: the user is about to spend their own key and must know it.
+ */
+/**
+ * Opt OUT of a CLI-hosted managed session.
+ *
+ * Present because "run with my own key" has to be expressible without logging
+ * out, and because a test that asserts argv forwarding must be able to say "this
+ * run is not about acquisition" rather than depend on whether the machine
+ * happens to be signed in.
+ */
+export declare const MANAGED_ENV_FLAG = "OVERSKY_SKY_CODE_MANAGED";
+/**
+ * The CLI's own flag, deliberately NOT `--agent`.
+ *
+ * `skrr code` forwards argv VERBATIM and the engine owns the bare flag namespace —
+ * `skrr code --agent reviewer` is the engine's flag and is pinned as such by
+ * `sky-code-passthrough.spec.ts`. A bare `--agent` here would steal it.
+ */
+export declare const OVERSKY_AGENT_FLAG = "--oversky-agent";
+/** The config key `skrr code` reads when the flag is absent. */
+export declare const AGENT_CONFIG_KEY = "skyCodeAgentId";
+/**
+ * The harness name this CLI is, as the server spells it.
+ *
+ * The server never takes it from the wire — `sessionInferenceRelay.js` fixes
+ * `provider: 'sky-code'` itself, because it selects the relay capability and
+ * composes the `provider_model` budget key, none of which is a caller's choice.
+ * So this is not a request parameter; it is the CLI naming itself in the two
+ * places that legitimately ask (the trust-tier lookup, and which default agent
+ * to establish).
+ */
+export declare const SKY_CODE_HARNESS = "sky-code";
+/**
+ * Mirrored from `@skrr-ai/inference-broker`, for the same reason
+ * `harness-tiers.ts` mirrors the daemon's trust table: importing the package
+ * would pull a loopback SERVER into `skrr code doctor` and into every unmanaged
+ * `skrr code` startup, to read two string constants.
+ *
+ * `sky-code-managed.spec.ts` asserts these against the package, so a rename there
+ * fails a test here rather than silently making the posture check blind.
+ */
+export declare const MANAGED_SESSION_ENV = "OVERSKY_MANAGED_SESSION";
+/**
+ * Which TRUST PLANE this process is on — a different question from whose model
+ * it is spending, and the two must not be answered from the same evidence.
+ *
+ * `MANAGED_SESSION_ENV` is written in exactly one place: the env map
+ * `startManagedInferenceBroker` returns. It answers "whose credential is this
+ * process spending?" — and since OSK-3892 that broker is hosted by the daemon OR
+ * by `skrr` itself. Keying an AUTHORITY answer on it therefore tells a user with
+ * no daemon at all that "a daemon adjudicates every tool call", which is the
+ * exact conflation `sessionAuthorityCheck`'s own docstring was written to warn
+ * about. It is not a subtle misread: bare `skrr code` never sets
+ * `OPENCODE_PERMISSION={"*":"ask"}` (only the daemon's backend does), so the
+ * engine consults its own allow-by-default config and nothing is adjudicated.
+ *
+ * Ordered deliberately: DAEMON IDENTITY FIRST. Only the daemon can set
+ * `OVERSKY_AUTONOMOUS_SESSION` or the runtime context a daemon session carries,
+ * so those are the trustworthy signals; the broker marker is set by whichever
+ * process hosts the broker and proves only that a credential is brokered. A
+ * CLI-hosted broker cannot forge the first pair, which is what makes the order
+ * load-bearing rather than stylistic.
+ */
+export type SkyCodeTrustPlane = 'daemon-supervised' | 'cli-brokered' | 'standalone';
+export declare function resolveTrustPlane(env: NodeJS.ProcessEnv): SkyCodeTrustPlane;
+export declare const BROKER_SOCKET_ENV = "OVERSKY_INFERENCE_BROKER_SOCKET";
+export type ManagedSkipKind = 'disabled' | 'daemon-brokered' | 'unsupported-platform' | 'insecure-server';
+export interface ManagedSkip {
+    kind: ManagedSkipKind;
+    /** One clause, phrased to complete "managed inference not used: …". */
+    detail: string;
+    /**
+     * Whether the user needs to be told. False for a skip that is the expected
+     * shape of the run; true for one that would otherwise read as a broken feature.
+     */
+    announce: boolean;
+}
+/**
+ * The effective skrr server for this process.
+ *
+ * Reads the environment FIRST and `loadConfig()` second, rather than relying on
+ * `loadConfig()`'s own env overlay, because `runDoctor` passes a synthetic env: a
+ * posture computed from the real `process.env` while claiming to describe the
+ * supplied one is a diagnostic that lies.
+ */
+export declare function skyCodeServerUrl(env?: NodeJS.ProcessEnv): string;
+/**
+ * Why this process would NOT host a managed session — or `null` if it would.
+ *
+ * Structural only, on purpose. "Not signed in", "no agent named", "policy denied"
+ * are all discovered by the acquisition itself and reported as fallbacks; putting
+ * them here would make `skrr code doctor` read the keychain and hit the network to
+ * print a posture line.
+ */
+export declare function managedSkipReason(env?: NodeJS.ProcessEnv): ManagedSkip | null;
+/**
+ * Take `--oversky-agent` out of the argv bound for the engine.
+ *
+ * Unconditional — the engine must never see a flag it does not declare, whether
+ * or not this run ends up brokering. Both spellings are accepted, and the
+ * space-separated form consumes its value token.
+ *
+ * Everything else is spliced out IN PLACE: `sky-code-passthrough.spec.ts` asserts
+ * exact array equality, so order and adjacency are the contract, and a flag
+ * separated from its value is a different command.
+ */
+export declare function takeOverskyAgentFlag(passthrough: readonly string[]): {
+    agentRef?: string;
+    engineArgv: string[];
+};
+/**
+ * The model the user named to the ENGINE, if any.
+ *
+ * Read rather than declared: the model is the engine's flag and stays the
+ * engine's flag. It is read because it is also the thing the lease must be
+ * admitted for — the broker rejects any request whose model is outside the lease,
+ * so admitting a different model than the engine will ask for produces a session
+ * that authenticates and then refuses every turn.
+ */
+export declare function namedEngineModel(passthrough: readonly string[]): string | undefined;
+/**
+ * Put the ADMITTED model into the engine's argv.
+ *
+ * Necessary, not cosmetic. The lease binds exactly one model, and the broker
+ * rejects locally when the child asks for another — so a session where the engine
+ * picks its own default is a session that fails on the first turn. The daemon
+ * solves this by overwriting `request.model` with the broker's `clientModelId`
+ * before the ACP handshake; a standalone CLI has no handshake, so the engine's own
+ * `--model` flag is the channel.
+ *
+ * Inserted immediately after the subcommand rather than appended, so it cannot
+ * land after a positional prompt and depend on the engine parser tolerating
+ * trailing flags. Never inserted when the user named a model: then the lease was
+ * admitted for THEIR model and re-stating it would be at best redundant and at
+ * worst a conflicting duplicate.
+ */
+export declare function withManagedModel(subcommand: string | null, args: readonly string[], model: string | undefined): string[];
+/**
+ * The posture line `skrr code doctor` prints.
+ *
+ * Rule 1 of the doctor module holds: this reports the socket PATH and whether the
+ * socket exists, never the relay secret that authenticates against it and never
+ * the `agst_` capability that never enters a child env in the first place.
+ */
+export declare function managedInferencePosture(env?: NodeJS.ProcessEnv): {
+    status: 'ok' | 'warn';
+    detail: string;
+    remedy?: string;
+};

package/dist/lib/sky-code-managed.js

@@ -0,0 +1,354 @@
+"use strict";
+/**
+ * OSK-3892 — the DECISION half of a CLI-hosted managed skrr Code session.
+ *
+ * skrr Code is standalone-capable and daemon-preferred: when a daemon is in the
+ * loop it brokers inference, and when a human just ran `skrr login` the CLI hosts
+ * the broker itself. This module answers the two questions that must be answered
+ * BEFORE any credential exists —
+ *
+ *   would this process broker, and if not, why not?
+ *   what does the engine's own argv say about the model, and what must be
+ *   removed from it before the engine sees it?
+ *
+ * — and it answers them from the environment alone.
+ *
+ * ── Why the decision is separated from the acquisition ─────────────────────
+ *
+ * Everything here is pure (env, a config read, one `existsSync`) and imports no
+ * auth, no data-provider and no broker. That is what lets `skrr code doctor` report
+ * the posture without configuring the auth plane, and it keeps
+ * `sky-code-doctor.ts` honest about being safe to run in any context. The
+ * acquisition and the `execEngine` hooks that drive it live in
+ * `sky-code-broker.ts`, which the `skrr code` commands import directly.
+ *
+ * ── Invariant I4: managed / BYOK / offline never silently become each other ─
+ *
+ * So a skip has TWO kinds. A structural one ("a daemon already brokers this",
+ * "the operator turned it off") is expected and silent — announcing it on every
+ * daemon-spawned invocation would be noise nobody reads. A skip that would
+ * otherwise look like a broken feature ("your server is not HTTPS") is announced,
+ * once, on stderr. Acquisition failures are always announced, for the same
+ * reason: the user is about to spend their own key and must know it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROKER_SOCKET_ENV = exports.MANAGED_SESSION_ENV = exports.SKY_CODE_HARNESS = exports.AGENT_CONFIG_KEY = exports.OVERSKY_AGENT_FLAG = exports.MANAGED_ENV_FLAG = void 0;
+exports.resolveTrustPlane = resolveTrustPlane;
+exports.skyCodeServerUrl = skyCodeServerUrl;
+exports.managedSkipReason = managedSkipReason;
+exports.takeOverskyAgentFlag = takeOverskyAgentFlag;
+exports.namedEngineModel = namedEngineModel;
+exports.withManagedModel = withManagedModel;
+exports.managedInferencePosture = managedInferencePosture;
+const node_fs_1 = require("node:fs");
+const config_1 = require("./config");
+const runtime_context_1 = require("./runtime-context");
+/**
+ * Opt OUT of a CLI-hosted managed session.
+ *
+ * Present because "run with my own key" has to be expressible without logging
+ * out, and because a test that asserts argv forwarding must be able to say "this
+ * run is not about acquisition" rather than depend on whether the machine
+ * happens to be signed in.
+ */
+exports.MANAGED_ENV_FLAG = 'OVERSKY_SKY_CODE_MANAGED';
+/**
+ * The CLI's own flag, deliberately NOT `--agent`.
+ *
+ * `skrr code` forwards argv VERBATIM and the engine owns the bare flag namespace —
+ * `skrr code --agent reviewer` is the engine's flag and is pinned as such by
+ * `sky-code-passthrough.spec.ts`. A bare `--agent` here would steal it.
+ */
+exports.OVERSKY_AGENT_FLAG = '--oversky-agent';
+/** The config key `skrr code` reads when the flag is absent. */
+exports.AGENT_CONFIG_KEY = 'skyCodeAgentId';
+/**
+ * The harness name this CLI is, as the server spells it.
+ *
+ * The server never takes it from the wire — `sessionInferenceRelay.js` fixes
+ * `provider: 'sky-code'` itself, because it selects the relay capability and
+ * composes the `provider_model` budget key, none of which is a caller's choice.
+ * So this is not a request parameter; it is the CLI naming itself in the two
+ * places that legitimately ask (the trust-tier lookup, and which default agent
+ * to establish).
+ */
+exports.SKY_CODE_HARNESS = 'sky-code';
+/**
+ * Mirrored from `@skrr-ai/inference-broker`, for the same reason
+ * `harness-tiers.ts` mirrors the daemon's trust table: importing the package
+ * would pull a loopback SERVER into `skrr code doctor` and into every unmanaged
+ * `skrr code` startup, to read two string constants.
+ *
+ * `sky-code-managed.spec.ts` asserts these against the package, so a rename there
+ * fails a test here rather than silently making the posture check blind.
+ */
+exports.MANAGED_SESSION_ENV = 'OVERSKY_MANAGED_SESSION';
+function resolveTrustPlane(env) {
+    if (env.OVERSKY_AUTONOMOUS_SESSION === '1' || (0, runtime_context_1.readRuntimeContext)(env).isDaemonSession) {
+        return 'daemon-supervised';
+    }
+    if (env[exports.MANAGED_SESSION_ENV] === '1')
+        return 'cli-brokered';
+    return 'standalone';
+}
+exports.BROKER_SOCKET_ENV = 'OVERSKY_INFERENCE_BROKER_SOCKET';
+/**
+ * The effective skrr server for this process.
+ *
+ * Reads the environment FIRST and `loadConfig()` second, rather than relying on
+ * `loadConfig()`'s own env overlay, because `runDoctor` passes a synthetic env: a
+ * posture computed from the real `process.env` while claiming to describe the
+ * supplied one is a diagnostic that lies.
+ */
+function skyCodeServerUrl(env = process.env) {
+    const fromEnv = (env.OVERSKY_BASE_URL || env.OVERSKY_SERVER_URL || '').trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return (0, config_1.loadConfig)().baseURL;
+    }
+    catch {
+        // A corrupt config is its own failure with its own message elsewhere; here it
+        // simply means the posture is unknowable, and `managedSkipReason` reports that
+        // as an insecure/unusable server rather than guessing a default.
+        return '';
+    }
+}
+function isHttpsUrl(value) {
+    try {
+        return new URL(value).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The server URL as a diagnostic is allowed to say it: SCHEME AND HOST ONLY.
+ *
+ * `skyCodeServerUrl` returns `OVERSKY_BASE_URL` / `OVERSKY_SERVER_URL` /
+ * `loadConfig().baseURL` unmodified, and a URL may legally carry userinfo — so
+ * `https://user:s3cret@host` put a password into `skrr code doctor --json`, which
+ * `docs/cli/SKRR_CODE.md` calls safe to paste into a ticket and promises never
+ * contains key material. Not hypothetical: `buildManagedInferenceRelayCredential`
+ * explicitly refuses a base URL carrying `username || password`, which is exactly
+ * the shape that reaches this line before being refused.
+ *
+ * `origin` also drops path, query and fragment. Nothing here needs them, and each
+ * is another place a token can hide.
+ */
+function serverOrigin(value) {
+    try {
+        const url = new URL(value);
+        // `origin` is the string "null" for a non-special scheme (e.g. `data:`), which
+        // would print as a server named null rather than as an unusable value.
+        return url.origin && url.origin !== 'null' ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+function insecureServerDetail(serverUrl) {
+    if (!serverUrl)
+        return 'no skrr server is configured';
+    const origin = serverOrigin(serverUrl);
+    if (!origin)
+        return 'the configured skrr server is not a usable URL';
+    return `${origin} is not an HTTPS skrr server`;
+}
+function envFlagIsOff(raw) {
+    if (raw == null)
+        return false;
+    return ['0', 'false', 'no', 'off'].includes(raw.trim().toLowerCase());
+}
+/**
+ * Why this process would NOT host a managed session — or `null` if it would.
+ *
+ * Structural only, on purpose. "Not signed in", "no agent named", "policy denied"
+ * are all discovered by the acquisition itself and reported as fallbacks; putting
+ * them here would make `skrr code doctor` read the keychain and hit the network to
+ * print a posture line.
+ */
+function managedSkipReason(env = process.env) {
+    // Already inside one. A second broker would double-wrap the relay: the child
+    // would talk to our loopback, which would talk to the parent's loopback, and the
+    // request envelope would be enforced twice against one lease.
+    if (env[exports.MANAGED_SESSION_ENV] === '1') {
+        return {
+            kind: 'daemon-brokered',
+            detail: 'this process is already inside a managed session',
+            announce: false,
+        };
+    }
+    // A daemon-dispatched or daemon-delegated session: the daemon owns the
+    // credential, and `apiFetch` here is bound to the session principal rather than
+    // the human's, so an acquisition would mint a second lease under it.
+    if (env.OVERSKY_AUTONOMOUS_SESSION === '1' || (0, runtime_context_1.readRuntimeContext)(env).isDaemonSession) {
+        return {
+            kind: 'daemon-brokered',
+            detail: 'a daemon session already brokers inference for this process',
+            announce: false,
+        };
+    }
+    if (envFlagIsOff(env[exports.MANAGED_ENV_FLAG])) {
+        return {
+            kind: 'disabled',
+            detail: `${exports.MANAGED_ENV_FLAG} is off`,
+            announce: false,
+        };
+    }
+    if (process.platform === 'win32') {
+        // `startManagedInferenceBroker` refuses Windows: the broker needs a verified
+        // local IPC transport and only the Unix socket path is reviewed. Reported
+        // rather than attempted, so the user gets a sentence instead of a throw.
+        return {
+            kind: 'unsupported-platform',
+            detail: 'the local inference broker has no reviewed Windows transport yet',
+            announce: true,
+        };
+    }
+    const serverUrl = skyCodeServerUrl(env);
+    if (!isHttpsUrl(serverUrl)) {
+        // The single most likely reason a developer sees BYOK when they expected
+        // managed: `buildManagedInferenceRelayCredential` requires HTTPS, and
+        // `OVERSKY_BASE_URL=http://localhost:3080` is a normal dev override. Named
+        // explicitly, because "managed inference is broken" is the wrong conclusion.
+        return {
+            kind: 'insecure-server',
+            // Three distinct states, and the temptation to collapse the last two by
+            // echoing the raw value is exactly what `serverOrigin` exists to refuse.
+            detail: insecureServerDetail(serverUrl),
+            announce: true,
+        };
+    }
+    return null;
+}
+/**
+ * Take `--oversky-agent` out of the argv bound for the engine.
+ *
+ * Unconditional — the engine must never see a flag it does not declare, whether
+ * or not this run ends up brokering. Both spellings are accepted, and the
+ * space-separated form consumes its value token.
+ *
+ * Everything else is spliced out IN PLACE: `sky-code-passthrough.spec.ts` asserts
+ * exact array equality, so order and adjacency are the contract, and a flag
+ * separated from its value is a different command.
+ */
+function takeOverskyAgentFlag(passthrough) {
+    const engineArgv = [];
+    let agentRef;
+    for (let i = 0; i < passthrough.length; i += 1) {
+        const token = passthrough[i];
+        if (token === exports.OVERSKY_AGENT_FLAG) {
+            // Last one wins, matching how every argv parser treats a repeated flag.
+            const value = passthrough[i + 1];
+            // A trailing `--oversky-agent` with no value must not swallow the next
+            // token (there is none) nor leave the flag in the argv.
+            if (value !== undefined && !value.startsWith('-')) {
+                agentRef = value;
+                i += 1;
+            }
+            continue;
+        }
+        if (token.startsWith(`${exports.OVERSKY_AGENT_FLAG}=`)) {
+            agentRef = token.slice(exports.OVERSKY_AGENT_FLAG.length + 1);
+            continue;
+        }
+        engineArgv.push(token);
+    }
+    const trimmed = agentRef?.trim();
+    return { ...(trimmed ? { agentRef: trimmed } : {}), engineArgv };
+}
+/**
+ * The model the user named to the ENGINE, if any.
+ *
+ * Read rather than declared: the model is the engine's flag and stays the
+ * engine's flag. It is read because it is also the thing the lease must be
+ * admitted for — the broker rejects any request whose model is outside the lease,
+ * so admitting a different model than the engine will ask for produces a session
+ * that authenticates and then refuses every turn.
+ */
+function namedEngineModel(passthrough) {
+    for (let i = 0; i < passthrough.length; i += 1) {
+        const token = passthrough[i];
+        if (token === '-m' || token === '--model') {
+            const value = passthrough[i + 1];
+            if (value !== undefined && !value.startsWith('-'))
+                return value;
+            continue;
+        }
+        for (const prefix of ['--model=', '-m=']) {
+            if (token.startsWith(prefix)) {
+                const value = token.slice(prefix.length).trim();
+                if (value)
+                    return value;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Put the ADMITTED model into the engine's argv.
+ *
+ * Necessary, not cosmetic. The lease binds exactly one model, and the broker
+ * rejects locally when the child asks for another — so a session where the engine
+ * picks its own default is a session that fails on the first turn. The daemon
+ * solves this by overwriting `request.model` with the broker's `clientModelId`
+ * before the ACP handshake; a standalone CLI has no handshake, so the engine's own
+ * `--model` flag is the channel.
+ *
+ * Inserted immediately after the subcommand rather than appended, so it cannot
+ * land after a positional prompt and depend on the engine parser tolerating
+ * trailing flags. Never inserted when the user named a model: then the lease was
+ * admitted for THEIR model and re-stating it would be at best redundant and at
+ * worst a conflicting duplicate.
+ */
+function withManagedModel(subcommand, args, model) {
+    if (!model)
+        return [...args];
+    const at = subcommand === null ? 0 : 1;
+    return [...args.slice(0, at), '--model', model, ...args.slice(at)];
+}
+/**
+ * The posture line `skrr code doctor` prints.
+ *
+ * Rule 1 of the doctor module holds: this reports the socket PATH and whether the
+ * socket exists, never the relay secret that authenticates against it and never
+ * the `agst_` capability that never enters a child env in the first place.
+ */
+function managedInferencePosture(env = process.env) {
+    if (env[exports.MANAGED_SESSION_ENV] === '1') {
+        const socket = (env[exports.BROKER_SOCKET_ENV] || '').trim();
+        if (!socket) {
+            return {
+                status: 'warn',
+                detail: `${exports.MANAGED_SESSION_ENV}=1 but no ${exports.BROKER_SOCKET_ENV} is present — this process cannot reach a broker`,
+                remedy: 'Do not set the managed marker by hand; let `skrr code` or the daemon set it.',
+            };
+        }
+        return {
+            status: 'ok',
+            detail: `inside a managed session; broker socket ${socket}` +
+                `${(0, node_fs_1.existsSync)(socket) ? '' : ' (gone — the parent broker has exited)'}`,
+        };
+    }
+    const skip = managedSkipReason(env);
+    if (!skip) {
+        // Origin only — see `serverOrigin`. Reaching here means the URL parsed and is
+        // HTTPS, so the fallback is unreachable and is written as an assertion rather
+        // than as a guess about what to print.
+        return {
+            status: 'ok',
+            detail: `would broker a managed session against ${serverOrigin(skyCodeServerUrl(env)) ?? 'the configured skrr server'}`,
+        };
+    }
+    return {
+        status: skip.announce ? 'warn' : 'ok',
+        detail: `would NOT broker — ${skip.detail}`,
+        ...(skip.kind === 'insecure-server'
+            ? {
+                remedy: 'Managed inference needs an HTTPS skrr server. Point the CLI at one ' +
+                    '(`skrr login --base-url https://…`) or keep using your own provider key.',
+            }
+            : {}),
+    };
+}