agent-shim 7.6.1 → 7.8.0

package/dist/types/index.d.ts

@@ -7,6 +7,8 @@
  * - the per-identity usage snapshot a statusline or launcher reads: its schema and the reader over an injected filesystem;
  * - the state root's layout (`resolveAgentShimHome`, `resolveLayoutPaths`, `buildLayoutPaths`), which includes adopting an existing `~/.claude-use` in place, and the Zod schema and inferred type of every configuration file (identity, configuration profile, provider, pool, directory rules, global config, credential), so a tool can validate or generate them with the same definitions the CLI uses.
  *
+ * Creating and changing identities, configuration profiles, providers, pools and directory rules: the `*Store` modules, which take the state root's `LayoutPaths`, return typed values and throw `CliError` subclasses.
+ *
  * Everything the CLI alone needs (commander wiring, prompts, `doctor`, `check`) is deliberately not exported here.
  */
 export { resolveDecisions, topLevelNames, type ResolveDecisionsInput, type ResolvedState } from "./resolve/pipeline";
@@ -24,3 +26,8 @@ export { AMBIENT_CREDENTIAL_VARS, detectAmbientCredential, evaluateAmbientCreden
 export { buildLayoutPaths, resolveAgentShimHome, resolveClaudeHome, resolveLayoutPaths, type LayoutPaths } from "./paths";
 export { CliError, EXIT_FAILURE, EXIT_USAGE, UsageError } from "./cliError";
 export { CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleSchema, DirectoryRulesSchema, EntryValueSchema, GlobalConfigSchema, IdentitySchema, PoolNameSchema, PoolSchema, PortableConfigSchema, ProviderSchema, WhenSchema, type CategoryMap, type ConfigProfile, type Credential, type CredentialSource, type DirectoryRule, type DirectoryRules, type EntryValue, type GlobalConfig, type Identity, type Pool, type PortableConfig, type Provider, type WhenCondition, } from "./config/schema";
+export { addIdentity, IdentityAlreadyExistsError, IdentityNotFoundError, identityExists, InvalidIdentityNameError, isIdentityDirectoryName, listIdentities, readActiveIdentity, readIdentity, removeIdentity, setAllowAmbientCredential, setDefaultConfigProfile, setIdentityCredential, useIdentity, type IdentityCredentialChange, type IdentityListEntry, type IdentityListing, type UnreadableIdentityListEntry, } from "./identityStore";
+export { createProfile, InvalidCategoryNameError, listProfiles, ProfileAlreadyExistsError, ProfileNotFoundError, profileExists, readGlobalConfig, readProfile, removeProfile, setGlobalDefaultProfile, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, type ProfileListEntry, } from "./configProfilesStore";
+export { addProvider, describeProviderEndpoint, InvalidProviderNameError, LegacyProviderFileError, listProviders, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, providerExists, readProvider, removeProvider, updateProvider, type AddProviderInput, type ProviderListEntry, type UpdateProviderInput, } from "./providersStore";
+export { addPool, PoolNotFoundError, readPools, removePool, requirePool, setPool } from "./poolStore";
+export { addDirectoryRule, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, listDirectoryRules, readDirectoryRules, removeDirectoryRule, updateDirectoryRule, writeDirectoryRules, type AddDirectoryRuleOptions, type UpdateDirectoryRuleOptions, } from "./directoryRulesStore";

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

@@ -0,0 +1,96 @@
+import type { LaunchFlags, Provider } from "../config/schema";
+import { type ResolvedCredential } from "../credential";
+import type { FrontDoorUp, HeadroomUp } from "./ports";
+/** The fully resolved launch flags for one launch. */
+export interface ResolvedLaunchFlags {
+    readonly skipPermissions: boolean;
+    readonly remoteControl: boolean;
+    readonly headroom: boolean;
+    /** Whether the launch routes through the front door so its requests are recorded, even with no provider and no headroom. */
+    readonly trackUsage: boolean;
+}
+/** The one-off command-line forms of the four boolean launch flags, each undefined when neither its positive nor its `--no-` form was given. */
+interface LaunchFlagOverrides {
+    readonly skipPermissions?: boolean;
+    readonly remoteControl?: boolean;
+    readonly headroom?: boolean;
+    readonly trackUsage?: boolean;
+}
+/** Inputs to `resolveLaunchFlags`. */
+export interface ResolveLaunchFlagsParams {
+    /** The cascade's resolved `launch` block, when a cascade was loaded for this launch. */
+    readonly cascade?: LaunchFlags;
+    /** The launch's own `--[no-]skip-permissions`, `--[no-]remote-control`, `--[no-]headroom` and `--[no-]track-usage` flags. */
+    readonly flags?: LaunchFlagOverrides;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** What `trackUsage` is when no flag, environment variable or cascade setting says: off, except for a pool launch, whose pick reads the usage the front door records. */
+    readonly trackUsageDefault?: boolean;
+}
+/**
+ * Resolves `skipPermissions`/`remoteControl`/`headroom`/`trackUsage` for one launch. Each setting has the same three forms, decided in the same order: an explicit command-line flag outright, then its environment variable (`AGENT_SHIM_SKIP_PERMISSIONS`, `AGENT_SHIM_REMOTE_CONTROL`, `AGENT_SHIM_HEADROOM`, `AGENT_SHIM_TRACK_USAGE`), then the cascade, and OFF when none of them says otherwise (`trackUsageDefault` changes that one fallback). The flag outranks the environment variable because it is the more deliberate of the two one-off forms (typed on this very command line, not inherited from a shell profile), and both outrank the cascade because they are one-off overrides of it.
+ *
+ * Environment variables read with the shared boolean vocabulary (`true`/`1`, `false`/`0`), so `AGENT_SHIM_SKIP_PERMISSIONS=0` switches off a cascade's `skipPermissions: true` for one launch; any other value throws `InvalidEnvBoolError`.
+ *
+ * This default-off posture is a deliberate change from the legacy bash tool, which passed `--dangerously-skip-permissions` unconditionally on every launch.
+ */
+export declare function resolveLaunchFlags(params: ResolveLaunchFlagsParams): ResolvedLaunchFlags;
+/**
+ * Builds the tool's own flag arguments from resolved launch flags.
+ *
+ * `--remote-control=` always carries a literal trailing `=` with an empty value — never bare `--remote-control` — confirmed as a deliberate fix in the legacy script's own git history to stop the flag from consuming the next positional argument as its value.
+ */
+export declare function buildFlagArgs(flags: ResolvedLaunchFlags): string[];
+/** Inputs to `buildArgv`. */
+export interface BuildArgvParams {
+    readonly toolFlags: readonly string[];
+    readonly extraFlags: readonly string[];
+    readonly passthrough: readonly string[];
+}
+/**
+ * Assembles the final argv passed to the real `claude` binary: tool flags, then `$CLAUDE_EXTRA_FLAGS`, then the user's own forwarded arguments, in that exact order.
+ *
+ * Extra flags must land BEFORE the passthrough args — confirmed load-bearing against real wrapper scripts (`cpl`, `mp`, `zpl`) that set `CLAUDE_EXTRA_FLAGS="--print"` and then pass a positional prompt afterwards; reversing this order would feed the prompt to `--print` as if it were a flag value instead of a trailing positional.
+ */
+export declare function buildArgv(params: BuildArgvParams): string[];
+/** The provider resolved for this launch, with its credential already resolved from the provider's credential block. */
+export interface ResolvedProvider {
+    readonly name: string;
+    readonly definition: Provider;
+    readonly credential: ResolvedCredential;
+}
+/** A resolved provider with the base URL its sessions are sent to: the front door's provider-scoped address, which exists only once the door is up and is the same shape for both kinds (the door is what decides where the request goes from there). */
+export interface RoutedProvider extends ResolvedProvider {
+    readonly baseUrl: string;
+}
+/** Inputs to `buildEnv`. */
+export interface BuildEnvParams {
+    readonly baseEnv: Readonly<Record<string, string | undefined>>;
+    /** True when `CLAUDE_CONFIG_DIR` was already set and the escape hatch applied — `buildEnv` must leave it untouched in that case. */
+    readonly configDirEscapeHatch: boolean;
+    /** The identity name resolved for this launch, when one was resolved. */
+    readonly resolvedIdentityName?: string;
+    readonly identitiesDir: string;
+    /** The provider resolved for this launch, when one was resolved, with the base URL it routes to. Its credential is resolved by the caller because refusing an unusable one needs the caller's log/exit ports. */
+    readonly provider?: RoutedProvider;
+    /** The launching identity's own resolved credential, when it has a credential block and no provider was selected. A provider's credential authenticates against the provider's endpoint, so the identity's is never applied alongside one. */
+    readonly identityCredential?: ResolvedCredential;
+    /** The front door this launch routes through, when one is engaged (a provider is selected, or headroom resolved on). It is what the child talks to: its provider listener for a provider session, its CONNECT surface for an OAuth one. */
+    readonly frontdoor?: FrontDoorUp;
+    /** The headroom daemon this launch's requests must pass through (as the door's headroom hop), when headroom resolved on. The child never talks to it directly. */
+    readonly headroom?: HeadroomUp;
+    /** The per-launch session id, stamped into the session header the door identifies this launch's requests by. */
+    readonly sessionId: string;
+}
+/**
+ * Builds the environment the real `claude` binary is spawned with.
+ *
+ * When the `CLAUDE_CONFIG_DIR`-already-set escape hatch applied, or no identity was resolved at all (a bare launch with no active identity, matching the legacy script's own "no profile means plain `~/.claude`" behaviour), `CLAUDE_CONFIG_DIR` is left untouched. Otherwise `CLAUDE_CONFIG_DIR` is set to the resolved identity's own directory under `identitiesDir` — farm population into that directory is Phase 5's job, not this function's.
+ *
+ * A resolved provider is applied regardless of the identity outcome, because it selects which API endpoint the child talks to, not which login's data it sees: `ANTHROPIC_BASE_URL` points at the provider's routed base URL (always the front door's provider-scoped address), `AGENT_SHIM_PROVIDER` names the provider for the statusline, the provider's own `env` entries land verbatim, and its resolved credential is exported as its target's variable (`credentialVariables`), with the other credential variables removed so an ambient one inherited from the parent cannot outrank it. Without a provider, an identity's own resolved credential is exported the same way. The token only ever reaches this environment, never the child's argv or a log line.
+ *
+ * A resolved front door is the whole of the child's routing, on top of the provider: `ANTHROPIC_CUSTOM_HEADERS` gains the launcher-injected session headers (identity, session id, the launch's capability token, and, when headroom resolved on, the headroom flag and the project identity headroom scopes memory to), merged with any headers the provider's own `env` or the parent environment already set. The door strips every one of them before anything leaves the machine; the token is what authorises the session's requests at the door in the first place. `NODE_EXTRA_CA_CERTS` points at the door's trust bundle in both modes, because the child reaches the door over TLS signed by agent-shim's CA either way. With a provider, the child's HTTPS base URL already names the door's provider listener, so a process that merely binds that port cannot present a certificate the child accepts. Without one (an OAuth launch), the base URL is left exactly as the parent environment had it, because Claude Code enables Remote Control and connectors only against the real `api.anthropic.com`; routing happens one layer down instead, with `HTTPS_PROXY` pointing the child at the door's CONNECT surface and carrying the launch's capability as its proxy credential (the surface refuses any CONNECT without a live one), so the child still believes it is talking to the real `api.anthropic.com` while the surface's terminated TLS feeds the routed paths to the same pipeline. `HEADROOM_PROXY_URL` names the headroom daemon for anything else that wants it; the child never talks to that daemon directly, the door's hop does.
+ *
+ * `$CLAUDE_EXTRA_FLAGS` is never stripped from the child's environment: some wrappers set it two process-levels up and rely on inheritance through a `claude` invoked from inside a running session.
+ */
+export declare function buildEnv(params: BuildEnvParams): Record<string, string | undefined>;
+export {};

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.6.1",
+  "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>",