agent-shim 7.7.0 → 7.8.0

package/dist/types/launcher/identity.d.ts

@@ -0,0 +1,95 @@
+import { type LoadedFile } from "../config/load";
+import { type Identity } from "../config/schema";
+import type { FsPort } from "./ports";
+/** Which precedence rule produced an identity decision. */
+export type IdentityDecisionSource = 
+/** `CLAUDE_CONFIG_DIR` was already set: identity resolution is skipped entirely and the real binary uses whatever it already points to. */
+"config-dir-escape-hatch"
+/** A leading `@name` argv[0] positional, or its explicit form `--identity <name>`. */
+ | "argv"
+/** The `AGENT_SHIM_IDENTITY` environment variable. */
+ | "env"
+/** A directory rule pinning an identity to the current path. */
+ | "directory-pin"
+/** The persisted `~/.agent-shim/active-identity` file. */
+ | "active-identity-file"
+/** Nothing resolved an identity at all — a bare launch with no active identity. */
+ | "none";
+/** The pool a `pool:<name>` selector names, or undefined when `selector` names an identity directly. */
+export declare function poolNameOf(selector: string): string | undefined;
+/** The result of deciding which identity applies to this launch. */
+export interface IdentityDecision {
+    /** The resolved identity name. Absent when the escape hatch applied, when nothing resolved one, or when a pool was selected (the launcher picks a member from `pool`). */
+    readonly name?: string;
+    /** The pool selected by a `pool:<name>` selector, when the launch named a pool instead of an identity. */
+    readonly pool?: string;
+    readonly source: IdentityDecisionSource;
+    /** True when `CLAUDE_CONFIG_DIR` was already set and every step below was skipped as a result. */
+    readonly configDirEscapeHatch: boolean;
+}
+/** Inputs to `decideIdentity`, in the exact precedence order the README's CLI reference table documents. */
+export interface DecideIdentityParams {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** The identity `parseLauncherArgv` found in a leading `@name` or an `--identity <name>` flag, if either was given. */
+    readonly argv0Identity?: string;
+    /** An identity pinned to `$PWD` by a directory rule. Accepted as an already-resolved value here — the rules-loading code that produces it lands in Phase 4/5. */
+    readonly directoryPinnedIdentity?: string;
+    /** Reads the persisted active-identity file, returning undefined when it does not exist or is empty. Injected so this stays pure. */
+    readonly readActiveIdentityFile: () => string | undefined;
+}
+/**
+ * Decides which identity applies to this launch, in precedence order:
+ *
+ * 1. If `CLAUDE_CONFIG_DIR` is already set, skip identity/cascade resolution entirely: a deliberate carry-forward of the legacy script's own "don't override an explicit launcher" escape hatch.
+ * 2. A leading `@name` argv[0] positional, or `--identity <name>`.
+ * 3. The `AGENT_SHIM_IDENTITY` environment variable.
+ * 4. A directory-pinned identity from a directory rule.
+ * 5. The persisted `~/.agent-shim/active-identity` file.
+ *
+ * Each of steps 2 to 5 may name `pool:<name>` instead of an identity; the decision then carries `pool` and no `name`, and the launcher picks the member.
+ *
+ * An empty string counts as unset for `CLAUDE_CONFIG_DIR` and `AGENT_SHIM_IDENTITY`, consistent with how this project treats empty-string environment variables everywhere else (see `src/paths.ts` and the ambient-credential guard).
+ */
+export declare function decideIdentity(params: DecideIdentityParams): IdentityDecision;
+/** Which precedence rule produced a configuration-profile decision. */
+export type ConfigProfileDecisionSource = 
+/** An explicit `--config-profile` CLI flag. */
+"cli-flag"
+/** The `AGENT_SHIM_CONFIG_PROFILE` environment variable. */
+ | "env"
+/** A directory rule's `configProfile` selection for `$PWD`. */
+ | "directory-rule"
+/** The active identity's own declared `defaultConfigProfile`. */
+ | "identity-default"
+/** The user-global `~/.agent-shim/config.json` default. */
+ | "global-default"
+/** Nothing resolved a configuration profile at all. */
+ | "none";
+/** The result of deciding which configuration profile applies to this launch. */
+export interface ConfigProfileDecision {
+    readonly name?: string;
+    readonly source: ConfigProfileDecisionSource;
+}
+/** Inputs to `decideConfigProfile`, in the exact precedence order the README's "Configuration profiles" section documents. */
+export interface DecideConfigProfileParams {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly cliFlagConfigProfile?: string;
+    readonly directoryRuleConfigProfile?: string;
+    readonly identityDefaultConfigProfile?: string;
+    readonly globalDefaultConfigProfile?: string;
+}
+/**
+ * Decides which configuration profile applies to this launch, in precedence order:
+ *
+ * 1. An explicit `--config-profile` flag or `AGENT_SHIM_CONFIG_PROFILE` environment variable (this run only).
+ * 2. A directory rule's `configProfile` selection for `$PWD`.
+ * 3. The active identity's own declared default (`defaultConfigProfile` in its `identity.json`).
+ * 4. A global default (`~/.agent-shim/config.json`).
+ */
+export declare function decideConfigProfile(params: DecideConfigProfileParams): ConfigProfileDecision;
+/**
+ * Reads and validates one identity's `identity.json` from `<identitiesDir>/<name>/identity.json`, via `IdentitySchema`.
+ *
+ * Returns undefined when the file does not exist (e.g. the identity was resolved by name but never actually created — `agent-shim identity add` is Phase 4's job, not this one's). Throws `ConfigValidationError` when the file exists but fails validation, the same as any other config file in this project.
+ */
+export declare function loadIdentity(identitiesDir: string, name: string, fs: FsPort): LoadedFile<Identity> | undefined;

package/dist/types/poolStore.d.ts

@@ -0,0 +1,18 @@
+import { CliError } from "./cliError";
+import { type Pool } from "./config/schema";
+import type { LayoutPaths } from "./paths";
+/** Raised when a command names a pool that is not defined in the global config. */
+export declare class PoolNotFoundError extends CliError {
+    readonly poolName: string;
+    constructor(poolName: string);
+}
+/** The pools defined in `~/.agent-shim/config.json`, by name. */
+export declare function readPools(paths: LayoutPaths): Readonly<Record<string, Pool>>;
+/** The pool named `name`; throws `PoolNotFoundError` when none is defined. */
+export declare function requirePool(paths: LayoutPaths, name: string): Pool;
+/** Defines a new pool. Throws `InvalidPoolNameError` for a name `PoolNameSchema` rejects and `PoolAlreadyExistsError` for one already defined. */
+export declare function addPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
+/** Replaces an existing pool's members. Throws `PoolNotFoundError` when it is not defined. */
+export declare function setPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
+/** Removes a pool. Throws `PoolNotFoundError` when it is not defined. Anything that selected it (an active-identity file, a directory rule) is left for `doctor` to report, as with a removed identity. */
+export declare function removePool(paths: LayoutPaths, name: string): void;

package/dist/types/providersStore.d.ts

@@ -0,0 +1,137 @@
+import { type PROVIDER_CREDENTIAL_TARGETS, type PROVIDER_KINDS, type CodexProviderConfig, type CredentialCache, type CredentialSource, type Provider } from "./config/schema";
+import { CliError, UsageError } from "./cliError";
+import { type CredentialPort } from "./credential";
+import type { ResolvedProvider } from "./launcher/flags";
+import type { FsPort } from "./launcher/ports";
+import { type CascadeInput } from "./resolve/walk";
+import type { LayoutPaths } from "./paths";
+/** Raised by any operation that requires a provider to already exist, when it does not. */
+export declare class ProviderNotFoundError extends CliError {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Raised by `addProvider` when a provider with the given name already has a file. */
+export declare class ProviderAlreadyExistsError extends CliError {
+    readonly providerName: string;
+    constructor(providerName: string);
+}
+/**
+ * Raised by `addProvider` when `name` fails the provider naming rule: the same rule `IdentitySchema` applies to identity names (start with a letter or number, then letters, numbers, dots, hyphens, underscores, and at signs). Keeping the two rules identical means a name that works for one works for the other, and neither vocabulary can ever produce a path segment that escapes `providers/` or `identities/`.
+ */
+export declare class InvalidProviderNameError extends CliError {
+    readonly attemptedName: string;
+    constructor(attemptedName: string);
+}
+/** True when a provider file exists for `name`, regardless of whether it validates. */
+export declare function providerExists(paths: LayoutPaths, name: string): boolean;
+/** Written in a replacement in place of an old fixed `env.ANTHROPIC_AUTH_TOKEN` value, which is never printed: the person converting the file copies the value across themselves. */
+export declare const LEGACY_LITERAL_PLACEHOLDER = "<the value of env.ANTHROPIC_AUTH_TOKEN>";
+/** What converting one old-format provider file involves: the old fields it uses, and the whole file rewritten in the current format. */
+export interface LegacyProviderConversion {
+    readonly fields: readonly string[];
+    readonly replacement: Record<string, unknown>;
+}
+/**
+ * Recognises a provider file written in the format before the credential block (a `tokenEnv`, `tokenCommand` or `authScheme` field, or a credential variable in `env`, and no `credential`) and builds its exact replacement: `tokenEnv` becomes an `env` source, `tokenCommand` a `command` source, a non-empty fixed `env.ANTHROPIC_AUTH_TOKEN` a `literal` source (its value replaced by `LEGACY_LITERAL_PLACEHOLDER`, never printed), `authScheme` the `target`, and the credential variables leave `env`. Undefined for anything else, including a file that is merely invalid.
+ */
+export declare function legacyProviderConversion(raw: unknown): LegacyProviderConversion | undefined;
+/** Raised when a provider file is still in the format before the credential block, naming the old fields and giving the exact replacement. */
+export declare class LegacyProviderFileError extends CliError {
+    readonly filePath: string;
+    readonly conversion: LegacyProviderConversion;
+    constructor(filePath: string, conversion: LegacyProviderConversion);
+}
+/** Reads and validates one provider definition, or undefined when it does not exist. */
+export declare function readProvider(paths: LayoutPaths, name: string): Provider | undefined;
+/**
+ * Reads and validates one provider definition through an injected `FsPort`, the same way `loadIdentity` reads an `identity.json`: the launcher never touches the real filesystem directly, so provider loading must flow through the port it is already handed.
+ */
+export declare function loadProvider(providersDir: string, name: string, port: FsPort): Provider | undefined;
+/** One provider definition as reported by `listProviders`. */
+export interface ProviderListEntry {
+    readonly name: string;
+    readonly provider: Provider;
+}
+/** Lists every provider under `providersDir` that has a valid `<name>.json`. A file that fails validation is skipped here; `provider list` is the place a broken definition gets surfaced, not a launch. */
+export declare function listProviders(paths: LayoutPaths): readonly ProviderListEntry[];
+/** The credential targets a provider may use. */
+export type ProviderCredentialTarget = (typeof PROVIDER_CREDENTIAL_TARGETS)[number];
+/** The kinds of provider. */
+export type ProviderKind = (typeof PROVIDER_KINDS)[number];
+/** Where a provider sends its sessions, for display: an `http` provider's base URL, or the front door for a codex provider (whose address exists only at launch). */
+export declare function describeProviderEndpoint(provider: Provider): string;
+/** Everything `addProvider` writes into a fresh provider file. `baseUrl` is required for an `http` provider and refused for a codex one; `codex` applies only to a codex provider. */
+export interface AddProviderInput {
+    readonly kind?: ProviderKind;
+    readonly displayName: string;
+    readonly baseUrl?: string;
+    readonly sources: readonly CredentialSource[];
+    readonly target?: ProviderCredentialTarget;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly codex?: CodexProviderConfig;
+}
+/** Raised when a provider option does not fit the provider's kind: a base URL for a codex provider, a missing one for an http provider, or codex settings for an http provider. */
+export declare class ProviderKindMismatchError extends UsageError {
+    constructor(message: string);
+}
+/**
+ * Creates a new provider definition. Throws `ProviderAlreadyExistsError` when a provider with this name already has a file, `InvalidProviderNameError` when `name` fails the naming rule, and `ConfigValidationError` when the assembled definition fails `ProviderSchema` (e.g. a `baseUrl` that is not a URL) rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+export declare function addProvider(paths: LayoutPaths, name: string, input: AddProviderInput): Provider;
+/**
+ * The fields `updateProvider` changes. `sources` replaces the whole ordered source list (a list is set, not patched, since its order is its meaning); `target` changes where the token goes and keeps the sources. `env` entries merge over the existing ones and `unsetEnv` keys are then deleted.
+ */
+export interface UpdateProviderInput {
+    readonly displayName?: string;
+    readonly baseUrl?: string;
+    readonly sources?: readonly CredentialSource[];
+    readonly target?: ProviderCredentialTarget;
+    /** A new cache block, or false to remove it; undefined leaves the existing one. */
+    readonly cache?: CredentialCache | false;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly unsetEnv?: readonly string[];
+    /** Merged over a codex provider's existing settings: a field given here replaces that field, and `models` entries merge per tier. */
+    readonly codex?: CodexProviderConfig;
+}
+/**
+ * Updates an existing provider definition in place. Throws `ProviderNotFoundError` when it does not exist, and `ConfigValidationError` when the updated definition fails `ProviderSchema`, leaving the file untouched.
+ */
+export declare function updateProvider(paths: LayoutPaths, name: string, input: UpdateProviderInput): Provider;
+/** Deletes a provider definition. Throws `ProviderNotFoundError` when it does not exist. */
+export declare function removeProvider(paths: LayoutPaths, name: string): void;
+/**
+ * The provider name the cascade selects through `launch.provider`, if any layer sets one. Last layer wins, the same rule `flattenLayers` applies to every other launch flag.
+ */
+export declare function cascadeProviderName(cascade: CascadeInput): string | undefined;
+/** Inputs to `resolveProvider`. */
+export interface ResolveProviderParams {
+    readonly paths: LayoutPaths;
+    readonly port: FsPort;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Resolves the provider's credential sources. Omitted by a caller that cannot read secret files or run commands; a selected provider is then refused rather than launched without its credential. */
+    readonly credentials?: CredentialPort;
+    /** The `--provider <name>` flag's value, when one was given. It outranks any cascade layer, matching how the cliOverride layer composes last everywhere else. */
+    readonly cliProvider?: string;
+    /** The assembled-but-unflattened cascade for this launch, when one was loaded. Its layers are scanned for a `launch.provider` selection so a profile, directory rule, portable file, or the global config can pin a provider exactly the way they pin the other launch flags. */
+    readonly cascade?: CascadeInput;
+}
+/**
+ * The outcome of resolving this launch's provider: either a fully-resolved provider (definition plus its resolved credential), or a refusal the launcher turns into a stderr line and a non-zero exit.
+ *
+ * A provider whose credential block yields no token exits `CREDENTIAL_UNAVAILABLE_EXIT` (64), because the invocation cannot authenticate. An unknown provider name exits 1, matching every other "named thing not found" refusal in the launcher.
+ */
+export type ProviderResolution = {
+    readonly ok: true;
+    readonly provider: ResolvedProvider;
+    readonly warnings: readonly string[];
+} | {
+    readonly ok: false;
+    readonly status: number;
+    readonly message: string;
+};
+/**
+ * Resolves which API provider this launch routes through, if any: the `--provider` flag first, then the cascade's `launch.provider` selection. Returns undefined when nothing selected a provider at all.
+ *
+ * Pure over its injected ports, so the launcher's tests exercise refusals without touching a real providers directory, secret store or terminal: this function decides, and the caller owns the log/exit side effects.
+ */
+export declare function resolveProvider(params: ResolveProviderParams): ProviderResolution | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "7.7.0",
+  "version": "7.8.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",