@tangle-network/cli-agent-registry 0.0.0-stage → 0.14.0

package/dist/specs-BSELpX1h.d.mts

@@ -0,0 +1,415 @@
+import { t as HarnessSessionContract } from "./session-contract-BC75JdnA.mjs";
+import { SdkProviderAdapter, WellKnownInteractionKind, agentProfileSchema } from "@tangle-network/agent-interface";
+import { HarnessModelSupport, HarnessModelSupportOptions } from "@tangle-network/agent-interface/harness-capabilities";
+
+//#region src/cli-dir-layout.d.ts
+/**
+ * How a parked export reads a CLI's own directory (`.codex`, `.claude`, …)
+ * beyond the session stores its contract declares. Globs are relative to that
+ * directory, in the session-contract glob syntax (`*`, `**`).
+ *
+ * - `sessionData`: what holds a user's session, to be exported as a
+ *   transcript is. Until the export carries it, it is missing, and the box is
+ *   held.
+ * - `configAllow`: the CLI's own configuration and caches, withheld and named.
+ *
+ * - `credential`: what this CLI keeps in its directory that carries secrets
+ *   but no shared credential name says so (a directory of shell environment
+ *   snapshots, messaging keys): named, never sent, never missing. The names
+ *   every CLI shares are runtime-contracts credential-paths.ts
+ *   (`isNativeStoreCredentialPath`, `NATIVE_STORE_CREDENTIAL_NAMES`), checked
+ *   first; a spec lists here only what its own pinned version writes.
+ *
+ * Anything else in the directory is undeclared: missing, so a layout a CLI
+ * version adds holds the box until it is classified here.
+ */
+interface CliDirLayout {
+  sessionData: readonly string[];
+  configAllow: readonly string[];
+  credential: readonly string[];
+}
+/** What every CLI's directory is read with; a spec adds its own entries. */
+declare const DEFAULT_CLI_DIR_LAYOUT: CliDirLayout;
+/** A spec's additions to the default layout. */
+type CliDirLayoutAdditions = Partial<CliDirLayout>;
+/** The default layout with a spec's additions. */
+declare function mergeCliDirLayout(additions: CliDirLayoutAdditions | undefined): CliDirLayout;
+//#endregion
+//#region src/synthetic-router-model.d.mts
+declare const SYNTHETIC_ROUTER_MODEL: "tangle/canary-echo";
+//#endregion
+//#region src/spec.d.ts
+/**
+ * Capability descriptor surfaced via GET /backends.
+ * Mirrors `apps/orchestrator/src/routes/backends.ts` schema so the registry
+ * is the single source of truth for both the orchestrator UI surface and
+ * sidecar adapter selection.
+ */
+interface HarnessSpecCapabilities {
+  streaming: boolean;
+  toolUse: boolean;
+  reasoning: boolean;
+  multimodal: boolean;
+  contextWindow: number;
+  mcp: boolean;
+  /** Runtime bindings lowered by the profile materializer, independently of dynamic MCP mutation. */
+  runtimeAttachments?: {
+    mcp: true;
+  };
+  sessions: boolean;
+  configurable: boolean;
+  /**
+   * Interaction kinds this harness is *capable* of originating
+   * (permission/question/plan). Static "can it, if asked" — NOT whether a
+   * given session enabled them (that's the per-session adapter
+   * getCapabilities() + toggle config). Empty = never asks the user.
+   */
+  interactions: WellKnownInteractionKind[];
+  /**
+   * Whether the harness forwards image input parts to the model natively
+   * (an argv flag or a stdin content block carrying the image itself)
+   * rather than a `[Image: <ref>]` text-marker reference. Distinct from
+   * `multimodal`, which is static "can the model reason over images, if
+   * asked" — `imageInput` is about the delivery mechanism this harness
+   * actually uses, not the model's capability.
+   *
+   * Like `interactions`, this is static "can it, if asked" — a specific
+   * config may still degrade: codex delivers natively on the exec path but
+   * marker-only on interactive (permission/question/plan) turns until the
+   * app-server protocol carries image elements (#3586). Per-config truth is
+   * the runtime adapter's getCapabilities().
+   */
+  imageInput: boolean;
+}
+type CliAgentEnvExtraParser = "string" | "int" | "json";
+/**
+ * Model-tuple role an extra env var carries, for specs whose provider/mode
+ * ride the extras channel rather than a first-class {@link CliAgentEnvVars}
+ * field (opencode's OPENCODE_MODEL_PROVIDER / OPENCODE_MODEL_MODE). Lets
+ * spec-driven consumers (label codec, backend metadata) resolve the tuple
+ * without naming any backend's env vars. A spec that declares a `provider`
+ * role is authoritative for its provider value; specs without one leave
+ * provider resolution to the consumer (e.g. the router model slug's
+ * `provider/` prefix).
+ */
+type CliAgentEnvExtraRole = "provider" | "mode";
+interface CliAgentEnvExtra {
+  parser: CliAgentEnvExtraParser;
+  required?: boolean;
+  role?: CliAgentEnvExtraRole;
+}
+/**
+ * Env var name declared with `role` in this spec's extras, or undefined when
+ * the spec declares none. At most one extra may carry a given role (enforced
+ * by a registry test); the first declaration wins.
+ */
+declare function cliAgentEnvRoleName(spec: CliAgentSpec, role: CliAgentEnvExtraRole): string | undefined;
+interface CliAgentEnvVars {
+  apiKey?: string;
+  model?: string;
+  authMode?: string;
+  authFiles?: string;
+  /** Native subscription token; never delivered through a warm claim. */
+  oauthToken?: string;
+  baseUrl?: string;
+  /** Provider-specific extras keyed by env var name. */
+  extras?: Record<string, CliAgentEnvExtra>;
+}
+/**
+ * `inherit-home` means the spawned CLI reads $HOME from the sidecar process.
+ * `agent-home` means the adapter demotes to a fixed uid and forces $HOME to
+ * a fixed path (claude-code: uid=1000, /home/agent) when the sidecar runs as
+ * root. This is the only branch with a non-default home resolution.
+ */
+type CliAuthHome = {
+  kind: "inherit-home";
+} | {
+  kind: "agent-home";
+  uid: number;
+  home: string;
+};
+/**
+ * The wire protocol a harness speaks to the Tangle router.
+ *
+ * `openai-compat` (`/v1/chat/completions`) routes any provider's model — the
+ * router resolves a provider-prefixed slug verbatim. The other two are
+ * provider-native wires: the router passes that provider's own models through
+ * natively and translates every other model to chat completions (text, images
+ * and function tools, streamed or not; hosted tools such as web search are
+ * dropped), so each carries any router-served model. Measured 2026-10-15 with
+ * `zai/glm-5.3` on claude-code 2.1.300 (`/v1/messages`) and codex 0.162.1
+ * (`/v1/responses`): a plain turn and a tool turn completed on both.
+ */
+type CliAgentModelWire = "openai-compat" | "openai-responses" | "anthropic-messages";
+/** The wire a harness speaks; harnesses that declare none ride openai-compat. */
+declare function harnessModelWire(spec: CliAgentSpec): CliAgentModelWire;
+/**
+ * The model id a harness and model check reads: a `provider/model` slug as
+ * given, a bare id qualified by its tuple's vendor provider, and a bare id
+ * alone when the tuple names only the Router transport (agent-interface then
+ * resolves its provider from the id's family).
+ */
+declare function canonicalModelSlug(model: string | {
+  provider?: string;
+  model?: string;
+} | undefined): string | undefined;
+/**
+ * Whether a harness can run a model, read from the one capability table in
+ * `@tangle-network/agent-interface`: vendor locks (kimi-code runs Moonshot
+ * models) and pairs measured to fail on production. A refused pair is refused
+ * where it is chosen (create, run, an authored workflow action) with the
+ * returned message, rather than provisioning a box whose first model call
+ * fails. An absent model is the harness's own default and is always supported.
+ */
+declare function harnessModelSupportFor(harness: string, model: string | {
+  provider?: string;
+  model?: string;
+} | undefined, options?: HarnessModelSupportOptions): HarnessModelSupport;
+/**
+ * Env var names carrying this harness's claim-deliverable model tuple — the
+ * names a warm-claim rebind may deliver to a live sidecar: the model /
+ * base-URL / auth-mode roles plus declared extras. Deliberately EXCLUDES the
+ * credential-bearing roles: `apiKey` (a BYO key outside egress proxy-swap
+ * coverage would put a raw secret in the rebind body — the caller adds the
+ * name back only when its transport guarantees a dummy value) and `authFiles`
+ * (auth-file payloads are credential content and never ride a rebind).
+ */
+declare function cliAgentClaimEnvVarNames(spec: CliAgentSpec): string[];
+/**
+ * Sidecar lifecycle contract for a harness's adapter, declared as spec data
+ * so the backend manager, prewarm triggers, and execution guards key on
+ * capabilities instead of forking on a harness name. Omitted (or a field
+ * omitted) means the CLI default: a per-model-config adapter process with no
+ * shared server, no idle retention, no concurrency cap, and no prewarm.
+ */
+interface CliAgentRuntimeSpec {
+  /**
+   * The adapter fronts one long-lived provider server per workspace and the
+   * model is a per-request override. Instance identity is therefore
+   * `type + workspace (+ profile/hub tools)`, never the model tuple, and
+   * config matching compares credentials + server address instead of the
+   * full model config. Non-server-based harnesses key every distinct model
+   * tuple to its own adapter instance — collapsing them would bleed one
+   * session's model config into another session's process.
+   */
+  serverBased?: boolean;
+  /**
+   * Keep an idle instance (refCount 0) alive for the next acquisition — the
+   * prewarm-then-claim first-token path depends on this. `envVar` names the
+   * deployed kill switch: unset means retain; "0"/"false"/"no"/"off"
+   * disables retention.
+   */
+  warmRetention?: {
+    envVar: string; /** Retained when `envVar` is unset. Defaults to true. */
+    enabledByDefault?: boolean;
+  };
+  /**
+   * Cap concurrent instances of this harness. The cap is read from `envVar`
+   * at acquisition time; unset means unlimited.
+   */
+  concurrencyLimit?: {
+    envVar: string;
+  };
+  /**
+   * Prewarm an instance from environment defaults at boot and after
+   * claim-time env injection so the first session skips the server spawn
+   * (~1.6s on the first-token path). Requires `serverBased`: prewarming a
+   * per-model CLI adapter would mint an instance keyed by a model tuple the
+   * claimed session may never match.
+   */
+  prewarmable?: boolean;
+  /**
+   * The adapter guarantees a tool-disabled visible-output continuation turn
+   * (`input.disableTools`). Execution fails loudly for harnesses without it.
+   */
+  supportsToolDisabledTurns?: boolean;
+  /**
+   * The adapter accepts a host-env redaction hook and the sidecar MUST wire
+   * its sanitizer into the adapter constructor so the agent process only
+   * inherits sandbox-public vars, never internal platform secrets. The
+   * binding fails closed if this declaration ever drifts off.
+   */
+  redactsHostEnv?: boolean;
+}
+/**
+ * A tool the harness ships built in, surfaced verbatim on the sidecar's
+ * tool-introspection routes. Declared as spec data so those routes serve
+ * whatever the registry says instead of forking on a harness name; a spec
+ * that declares none reports tool introspection as unsupported.
+ */
+interface CliAgentBuiltinTool {
+  id: string;
+  name: string;
+  description: string;
+}
+interface CliAgentSpec {
+  name: string;
+  displayName: string;
+  description: string;
+  /** Durable message-store directory; omit when history requires a backend. */
+  messageStorageDir?: string;
+  /**
+   * What a parked export reads in this CLI's own directory beyond its session
+   * stores, added to DEFAULT_CLI_DIR_LAYOUT (cli-dir-layout.ts).
+   */
+  cliDirLayout?: CliDirLayoutAdditions;
+  envVars: CliAgentEnvVars;
+  runtime?: CliAgentRuntimeSpec;
+  /** Built-in tool inventory; omit when the harness declares none. */
+  builtinTools?: readonly CliAgentBuiltinTool[];
+  /**
+   * Operator-level tuning env names forwarded verbatim from a HOST process
+   * (orchestrator system env, host-agent process env) into every container —
+   * server log routing, retry/limit knobs, mock switches. NOT part of the
+   * claim-deliverable model tuple and never a credential channel: these names
+   * are excluded from the kernel-cmdline and rebind unions, and a secret-like
+   * name here would still be caught by the allowlist builders' secret-suffix
+   * guard. Omit for harnesses with no host-side tuning surface.
+   */
+  hostPassthroughEnvVars?: readonly string[];
+  /**
+   * Router wire this harness speaks. Omit for `openai-compat`, which every
+   * harness rides unless its CLI talks a provider-native protocol. Which models
+   * a harness can run is answered by {@link harnessModelSupportFor}; the model a
+   * managed session defaults to is `managedModelChain(name).chain[0]`.
+   */
+  modelWire?: CliAgentModelWire;
+  /**
+   * Hosts the vendor CLI must reach, allowed through egress only for a box
+   * running this harness. Declared beside {@link callerCredentialOnly} because
+   * a vendor-served harness cannot work without its vendor's API.
+   */
+  egressHosts?: readonly string[];
+  /**
+   * Whether this harness's native TUI can be launched PRE-SEEDED with an opening
+   * prompt (a launch arg the CLI submits once it is ready to read input).
+   *
+   * A caller that drives a TUI on the user's behalf — a workflow interactive run
+   * — always seeds one, so a harness without this can start a terminal but never
+   * receives the task. Declared here so the surface offering interactive runs and
+   * the sidecar that launches them cannot drift onto different sets; the actual
+   * argv shape stays with the launcher (`INTERACTIVE_INITIAL_PROMPT_ARGS`).
+   */
+  interactiveSeededPrompt?: boolean;
+  capabilities: HarnessSpecCapabilities;
+  /**
+   * The harness session contract (session-contract.ts): where the native
+   * session is stored, how its id is known, and which flags would disable
+   * it. Null only for a spec that runs no harness (`sessions: false`) or a
+   * harness listed in HARNESS_SESSION_UNSUPPORTED.
+   */
+  nativeSession: HarnessSessionContract | null;
+  /** Linux container caps. Defaults to ['SYS_PTRACE'] when omitted. */
+  securityCapabilities?: string[];
+  cliAuthHome: CliAuthHome;
+  hasCliAuth: boolean;
+  /**
+   * The harness completes a session on a caller-supplied OAuth bundle
+   * (`model.authFiles`) with no managed router key: its adapter scrubs the
+   * router pin under `authMode: "oauth"` and the CLI reaches the vendor's own
+   * subscription backend. A create for such a harness with auth files mints
+   * no router key.
+   */
+  byoOAuth?: boolean;
+  /**
+   * The Tangle Router cannot serve this harness: its CLI calls the vendor's own
+   * hosted service (amp: ampcode.com, cursor: api2.cursor.sh) and accepts no
+   * custom model endpoint. It runs only on the caller's credential (a key, a
+   * key reference, CLI auth, or login files through its `envVars.authFiles`
+   * channel), so it has no managed model chain: a create mints no Router key
+   * for it, is refused when it carries none, and its box gets no Router default
+   * model. The public backend catalog reports the flag. Every other harness
+   * starts on the Router when the caller brings no credential of its own.
+   */
+  callerCredentialOnly?: boolean;
+}
+type AdapterFactory = (logger: ProviderLogger) => SdkProviderAdapter;
+/** Bounded provider startup spans, timed by the operation's owner. */
+type ProviderPhase = "profile_materialize" | "session_prepare" | "native_resume" | "native_session_new" | "history_replay" | "native_session_bind" | "config_build" | "config_write" | "session_turn_wait" | "session_view_bind" | "mcp_proxy_lease" | "native_home_wait" | "dependency_prep" | "cli_spawn" | "cli_boot" | "cli_initialize" | "cli_authenticate" | "server_listening" | "session_open" | "mcp_ready_wait" | "prompt_dispatch" | "cli_ready_wait" | "warm_server_hit" | "warm_server_miss";
+type ProviderLogger = {
+  info: (msg: string, meta?: Record<string, unknown>) => void;
+  warn: (msg: string, meta?: Record<string, unknown>) => void;
+  error: (msg: string, meta?: Record<string, unknown>) => void;
+  debug: (msg: string, meta?: Record<string, unknown>) => void; /** Report one startup span; the host records it with the turn's phases. */
+  observePhase?: (phase: ProviderPhase, durationMs: number, scope?: "turn" | "prewarm") => void;
+};
+//#endregion
+//#region src/specs.d.ts
+/**
+ * Env var naming a sandbox's selected backend. Stamped into every create env
+ * by the orchestrator (`buildSidecarContainerConfig`); read by the sidecar's
+ * backend resolution (`resolveConfiguredBackend`) and by the host-agent's
+ * warm-claim env selection to pick which spec's env vars the rebind delivers.
+ */
+declare const AGENT_BACKEND_ENV_VAR = "AGENT_BACKEND";
+/**
+ * The managed-router model-key channel every backend shares: the box-side
+ * value is always the salted proxy dummy (`proxy-model-token.<salt>`), which
+ * the per-sandbox egress proxy swaps for the real budget-scoped key at the
+ * network boundary. The opencode-derived NAME is pinned naming debt: FC
+ * shared-snapshot salt recovery, resume re-key, and the egress proxy swap map
+ * all key on this literal, so renaming it bricks managed-model auth
+ * fleet-wide. Kept equal to the opencode spec's own apiKey declaration
+ * (enforced by a registry test).
+ */
+declare const MANAGED_MODEL_KEY_ENV_VAR = "OPENCODE_MODEL_API_KEY";
+/**
+ * Caller-owned auth by reference: the NAME of the box env var (a stored
+ * secret) that holds the provider's key. The orchestrator sets it only when it
+ * injected no managed key; the sidecar composes the named provider on that
+ * credential. A variable name, never a secret, so it may ride every channel a
+ * create's env takes to the guest — the kernel cmdline and a warm-claim rebind.
+ */
+declare const MANAGED_MODEL_KEY_NAME_ENV_VAR = "OPENCODE_MODEL_API_KEY_ENV";
+/**
+ * Env var names declared across ALL registered harness specs, grouped by
+ * their `CliAgentEnvVars` role. The ONE derivation every allowlist that must
+ * track "what env names can a backend legitimately use" builds from — the
+ * FC kernel-cmdline whitelist, the egress secret handling, the sidecar
+ * terminal scrub, the SSH env forward, and the rebind union below. Deriving
+ * from roles (not one flat set) lets each consumer apply its own security
+ * policy per role: apiKey and oauthToken names are secret channels.
+ * Native subscription tokens stay out of warm-claim delivery.
+ */
+declare function cliAgentEnvVarNamesByRole(): {
+  apiKey: ReadonlySet<string>;
+  oauthToken: ReadonlySet<string>;
+  model: ReadonlySet<string>;
+  baseUrl: ReadonlySet<string>;
+  authMode: ReadonlySet<string>;
+  authFiles: ReadonlySet<string>;
+  extras: ReadonlySet<string>;
+};
+/**
+ * Union of every spec's `hostPassthroughEnvVars` — the operator tuning names
+ * a host process (orchestrator system env, host-agent process env) may
+ * forward into containers. Request/caller env always keeps precedence at the
+ * host-agent boundary; the orchestrator system-env channel stays
+ * operator-authoritative. Replaces the old `OPENCODE_*` prefix forward,
+ * which leaked ANY stray host var with that prefix (model tuple and key
+ * included) into every tenant.
+ */
+declare function cliAgentHostPassthroughEnvVarNames(): ReadonlySet<string>;
+/**
+ * Union of every env var name a warm-claim rebind may deliver, across all
+ * registered harnesses. The ONE source both sides of the rebind derive from:
+ * the host-agent selects its delivery from it and the sidecar rebind route
+ * carves it out of the loader-control rejection, so the two can never drift
+ * into "host delivers a name the sidecar 400s" — which silently cold-paths
+ * every warm claim of that backend. Includes each spec's apiKey name because
+ * acceptance is a superset of delivery: the HOST decides which key names are
+ * safe to send (egress proxy-swap-covered only), while the sidecar must not
+ * reject a name a valid host may deliver.
+ */
+declare function claimDeliverableEnvVarNames(): ReadonlySet<string>;
+declare const CLI_AGENT_SPECS: readonly CliAgentSpec[];
+declare function getSpec(name: string): CliAgentSpec | undefined;
+/**
+ * The directory, relative to a session's storage path, where a backend's
+ * message log lives: the one value adapters, the sidecar and the parked
+ * export read. Throws for a backend whose spec names none.
+ */
+declare function messageStorageDirOf(name: string): string;
+//#endregion
+export { CliDirLayout as A, ProviderPhase as C, harnessModelSupportFor as D, cliAgentEnvRoleName as E, DEFAULT_CLI_DIR_LAYOUT as M, mergeCliDirLayout as N, harnessModelWire as O, ProviderLogger as S, cliAgentClaimEnvVarNames as T, CliAgentModelWire as _, agentProfileSchema as a, CliAuthHome as b, cliAgentHostPassthroughEnvVarNames as c, AdapterFactory as d, CliAgentBuiltinTool as f, CliAgentEnvVars as g, CliAgentEnvExtraRole as h, MANAGED_MODEL_KEY_NAME_ENV_VAR as i, CliDirLayoutAdditions as j, SYNTHETIC_ROUTER_MODEL as k, getSpec as l, CliAgentEnvExtraParser as m, CLI_AGENT_SPECS as n, claimDeliverableEnvVarNames as o, CliAgentEnvExtra as p, MANAGED_MODEL_KEY_ENV_VAR as r, cliAgentEnvVarNamesByRole as s, AGENT_BACKEND_ENV_VAR as t, messageStorageDirOf as u, CliAgentRuntimeSpec as v, canonicalModelSlug as w, HarnessSpecCapabilities as x, CliAgentSpec as y };
+//# sourceMappingURL=specs-BSELpX1h.d.mts.map