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

package/dist/spec-CcvTM7-j.d.mts

@@ -0,0 +1,346 @@
+import { t as HarnessSessionContract } from "./session-contract-BhzcbPRW.mjs";
+import { SdkProviderAdapter, WellKnownInteractionKind } 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 except `homeSessionData`, in 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 {
+  /** Auxiliary session files relative to the owning runtime HOME, outside its CLI directory. */
+  homeSessionData: readonly string[];
+  sessionData: readonly string[];
+  configAllow: readonly (string | {
+    path: string;
+    kind: "symlink";
+  })[];
+  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`: pairs measured to fail on production
+ * (and any vendor lock it declares). 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;
+  /** Adapter accepts host-env redaction; Sidecar must bind its sanitizer,
+   * admitting sandbox-public vars only and failing closed if this drifts off. */
+  redactsHostEnv?: boolean;
+  /** Native launch and MCP custody implement secret-profile UID/HOME isolation. */
+  secretProfileIsolation?: 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;
+  /** A capability the harness needs and Tangle sandboxes lack: creates are refused. */
+  unavailable?: {
+    capability: "docker";
+    reason: string;
+  };
+}
+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
+export { mergeCliDirLayout as C, DEFAULT_CLI_DIR_LAYOUT as S, harnessModelSupportFor as _, CliAgentEnvExtraRole as a, CliDirLayout as b, CliAgentRuntimeSpec as c, HarnessSpecCapabilities as d, ProviderLogger as f, cliAgentEnvRoleName as g, cliAgentClaimEnvVarNames as h, CliAgentEnvExtraParser as i, CliAgentSpec as l, canonicalModelSlug as m, CliAgentBuiltinTool as n, CliAgentEnvVars as o, ProviderPhase as p, CliAgentEnvExtra as r, CliAgentModelWire as s, AdapterFactory as t, CliAuthHome as u, harnessModelWire as v, CliDirLayoutAdditions as x, SYNTHETIC_ROUTER_MODEL as y };
+//# sourceMappingURL=spec-CcvTM7-j.d.mts.map