@wildo-ai/external-connectors-models 1.0.1 → 1.1.0

package/dist/esm/protocols/agent-client-protocol.external-connectors-models.schemas.js

@@ -0,0 +1,639 @@
+import { z } from "zod";
+import { ExternalProvider_OperationContextSchema, } from "../core/operations.external-connectors-models.schemas.js";
+import { APPLICATION_ENVIRONMENT, ExternalProvider_ExchangeProtocol_Configuration_BaseSchema, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_ExchangeProtocol_Profile_BaseSchema, ExternalProvider_ExchangeProtocol_Status_BaseSchema, } from "../core/commons.external-connectors-models.schemas.js";
+//===============================================================
+// Agent Client Protocol (ACP)
+// --------
+// Execution protocol for CODING AGENTS: a long-lived JSON-RPC 2.0 session over
+// stdio between Wildo (the ACP *client*) and an agent subprocess that reads and
+// writes a workspace, runs commands, and asks permission before doing so.
+//
+// This is Zed's Agent Client Protocol (agentclientprotocol.com), NOT IBM's
+// "Agent Communication Protocol" — that one is agent-to-agent and overlaps
+// `A2A_CONNECTOR`. The two share an acronym and nothing else.
+//
+// # Why this is not a one-shot CLI transport with extra fields
+//
+// The transport this REPLACED (removed 2026-08-27) modelled ONE-SHOT command
+// execution: compose argv, feed stdin, wait for exit, parse stdout. Every field
+// it owned (`outputParserMode`, `jsonOutputPath`, per-operation argument
+// templates) described that shape. A
+// coding agent is the opposite shape — a session that streams progress, calls
+// back into the client for permission, survives many turns, and reports token
+// usage as it goes. Modelling it as a one-shot text call is precisely what left
+// the previous lane with no token accounting, no permission channel, no
+// cancellation and no resumption: those are not missing features, they are
+// consequences of the wrong protocol shape.
+//
+// # Deliberately AGENT-NEUTRAL
+//
+// Wildo's default coding agent is Claude Code (through Zed's ACP adapter), but
+// nothing in this contract names it. Every agent-specific concept is either
+// negotiated at runtime (the agent advertises its capabilities and session
+// modes in its `initialize` / `session/new` responses) or authored as opaque
+// `sessionMetaExtensions`. That is what makes selecting a different registered
+// ACP agent a configuration change rather than a new execution lane.
+//===============================================================
+/**
+ * Where the agent subprocess runs.
+ *
+ * Only one host exists today, and it is the same constraint the coding lane has
+ * always had: the agent must share a filesystem with the workspace it mutates.
+ * A remote host is not a variant of this — it would need the workspace shipped
+ * to it, which is a different design, so it is deliberately not enumerated
+ * until it exists.
+ */
+export var AgentClientProtocol_RunnerHost;
+(function (AgentClientProtocol_RunnerHost) {
+    AgentClientProtocol_RunnerHost["BACKEND_SUBPROCESS"] = "backend_subprocess";
+})(AgentClientProtocol_RunnerHost || (AgentClientProtocol_RunnerHost = {}));
+/**
+ * How the spawned agent authenticates to its own model provider.
+ *
+ * ACP additionally defines a protocol-level `authenticate` method, advertised
+ * through the agent's `authMethods` array. That is NOT enumerated here: when an
+ * agent advertises auth methods the runner negotiates them at `initialize`
+ * time, which is a runtime handshake rather than authored configuration. These
+ * modes describe what the HOST does before the process starts.
+ */
+export var AgentClientProtocol_AuthMode;
+(function (AgentClientProtocol_AuthMode) {
+    /** The agent needs no credential (a local model, or an agent that refuses work). */
+    AgentClientProtocol_AuthMode["NONE"] = "none";
+    /**
+     * The agent resolves its own credential from host state — an operator's prior
+     * interactive login, a keychain entry, an ambient cloud identity. Wildo
+     * injects nothing and can see nothing. This is the correct mode for a
+     * developer-machine coding agent.
+     */
+    AgentClientProtocol_AuthMode["HOST_MANAGED"] = "host_managed";
+    /** Wildo resolves a secret by ref and injects it into the child environment. */
+    AgentClientProtocol_AuthMode["SECRET_REF_ENV_INJECTION"] = "secret_ref_env_injection";
+})(AgentClientProtocol_AuthMode || (AgentClientProtocol_AuthMode = {}));
+/**
+ * Which directory becomes the ACP session's `cwd`.
+ *
+ * ACP requires `cwd` to be an ABSOLUTE path and treats it as the session's
+ * primary filesystem context. The absolute path itself is never authored here:
+ * it is host authority supplied at invocation time, which is what makes a
+ * profile portable across applications and machines.
+ */
+export var AgentClientProtocol_WorkingDirectoryPolicy;
+(function (AgentClientProtocol_WorkingDirectoryPolicy) {
+    AgentClientProtocol_WorkingDirectoryPolicy["WORKSPACE_ROOT"] = "workspace_root";
+    AgentClientProtocol_WorkingDirectoryPolicy["WORKSPACE_RELATIVE_PATH"] = "workspace_relative_path";
+})(AgentClientProtocol_WorkingDirectoryPolicy || (AgentClientProtocol_WorkingDirectoryPolicy = {}));
+/**
+ * The MOST autonomy a session started from this profile may be granted.
+ *
+ * This is a Wildo-owned vocabulary, deliberately expressed in terms of what the
+ * CLIENT must still decide rather than in any agent's mode identifiers. Agents
+ * advertise their own modes at `session/new` (Claude's adapter offers
+ * `default`, `auto`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions`),
+ * and those identifiers are agent-specific strings — binding a provider profile
+ * to them would make the contract unusable for any other agent and would break
+ * the moment an agent renames one.
+ *
+ * It is a CEILING, not a selection: the caller (for application creation, the
+ * autonomy mode of the journey) chooses at or below it. An authored ceiling is
+ * what lets an application say "no session started from this profile may ever
+ * skip the permission gate" independently of what any individual run requests.
+ *
+ * Ordering is meaningful and increasing: PROMPT_ALWAYS < AUTO_ACCEPT_EDITS <
+ * UNRESTRICTED. Compare through {@link agentClientProtocolPermissionCeilingRank}
+ * rather than by string, so the ordering has one definition.
+ */
+export var AgentClientProtocol_PermissionCeiling;
+(function (AgentClientProtocol_PermissionCeiling) {
+    /**
+     * Every permission request the agent raises must be answered by the client.
+     *
+     * Note what this does and does not promise: it guarantees the CLIENT decides
+     * every request the agent RAISES, not that the agent raises one per action.
+     * Which tool calls escalate is the agent's own policy — measured against
+     * Claude's adapter, file edits and writes prompt while a read-only shell
+     * command does not. Treat this as "no blanket pre-approval", never as "a
+     * complete inventory of what the agent did"; that inventory comes from the
+     * tool-call stream and, authoritatively, from the change set.
+     */
+    AgentClientProtocol_PermissionCeiling["PROMPT_ALWAYS"] = "prompt_always";
+    /**
+     * File edits are auto-accepted; everything else must still be answered.
+     *
+     * "Must still be answered" is a promise the CLIENT keeps, and it is only
+     * keepable because the runner refuses to hand the decision to the agent.
+     * Measured live against Claude's adapter on 2026-08-27: selecting that
+     * agent's own `acceptEdits` session mode ALSO auto-approves arbitrary shell
+     * commands, so a mutating `printf > file` executed with no permission request
+     * at all and wrote outside the task's declared mutation scope. Under the
+     * strictest mode the identical prompt escalated and was denied, and nothing
+     * was written.
+     *
+     * So this ceiling is implemented by keeping the agent in its most-escalating
+     * mode and auto-allowing edit-kind requests HERE. The agent's similarly named
+     * mode is deliberately not selected: it grants strictly more than its name.
+     */
+    AgentClientProtocol_PermissionCeiling["AUTO_ACCEPT_EDITS"] = "auto_accept_edits";
+    /**
+     * The protocol's NON-MUTATING tool kinds are auto-accepted; everything else must still be
+     * answered — and with no human at the other end, that means denied.
+     *
+     * The read-only lane. `read`, `search`, `fetch` and `think` are exactly the kinds the Agent Client
+     * Protocol itself classes as non-mutating; `edit`, `delete` and `move` are its mutating set and are
+     * refused here, as are `execute` (which can mutate anything) and `other` (unclassified, so
+     * fail-closed).
+     *
+     * Added 2026-08-29 because neither existing ceiling could express a research agent, MEASURED
+     * rather than assumed: a probe under {@link PROMPT_ALWAYS} with every location refused had both
+     * `WebFetch` and `WebSearch` arrive as `toolKind: 'fetch'` and be `ceiling_refused`, and the agent
+     * ended its turn saying it would not guess a price from memory. So PROMPT_ALWAYS denies research
+     * outright, and {@link AUTO_ACCEPT_EDITS} admits precisely the inverse of what research needs.
+     */
+    AgentClientProtocol_PermissionCeiling["AUTO_ACCEPT_READS"] = "auto_accept_reads";
+    /** No permission gate. Reserve for a disposable or isolated workspace. */
+    AgentClientProtocol_PermissionCeiling["UNRESTRICTED"] = "unrestricted";
+})(AgentClientProtocol_PermissionCeiling || (AgentClientProtocol_PermissionCeiling = {}));
+/**
+ * Increasing rank for {@link AgentClientProtocol_PermissionCeiling}; the single ordering definition.
+ *
+ * ## It is a CLAMP order, not a subset lattice — and that distinction is load-bearing
+ *
+ * Rank answers one question: how much is pre-approved without a human. It is used to LOWER a
+ * request that asks for more autonomy than its profile allows, never to reason about which
+ * permissions contain which.
+ *
+ * The sets are deliberately NOT nested. {@link AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_EDITS}
+ * (rank 2) admits the mutating kinds and still refuses `fetch`, while
+ * {@link AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS} (rank 1) admits `fetch` and refuses
+ * every mutating kind. Reading rank as containment would say the higher ceiling must also admit
+ * `fetch` — and making that true would hand every coding agent network access as a side effect of
+ * building a research lane. That is a change to the coding lane's posture and it needs its own
+ * evidence, not a corollary. Clamping still behaves correctly: a coding profile lowered to
+ * AUTO_ACCEPT_READS may fetch and may not edit, which is exactly what asking for less autonomy in
+ * the read direction should mean.
+ */
+export function agentClientProtocolPermissionCeilingRank(ceiling) {
+    switch (ceiling) {
+        case AgentClientProtocol_PermissionCeiling.PROMPT_ALWAYS:
+            return 0;
+        case AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS:
+            return 1;
+        case AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_EDITS:
+            return 2;
+        case AgentClientProtocol_PermissionCeiling.UNRESTRICTED:
+            return 3;
+    }
+}
+/**
+ * How much of the HOST MACHINE's agent configuration a session inherits.
+ *
+ * Coding agents read configuration from the filesystem — instructions, skills,
+ * slash commands, sub-agent personas, tool permissions — and they layer several
+ * scopes. Measured against Claude's ACP adapter, the default is to load ALL of
+ * them, including the operator's personal `~/.claude`: a probe session returned
+ * roughly forty commands and a persona belonging to the machine running it,
+ * none of which the application authored.
+ *
+ * That inheritance is not simply undesirable, which is why this is a three-way
+ * choice rather than a boolean. A dispatched coding task SHOULD read the
+ * application's own instructions and installed skills — that is how the
+ * application teaches the agent to use its framework. What it should not
+ * silently absorb is whoever happens to be logged in.
+ */
+export var AgentClientProtocol_HostConfigurationInheritance;
+(function (AgentClientProtocol_HostConfigurationInheritance) {
+    /** No filesystem-sourced agent configuration. The prompt is the whole instruction. */
+    AgentClientProtocol_HostConfigurationInheritance["ISOLATED"] = "isolated";
+    /**
+     * Configuration owned by the workspace (its committed instructions, its
+     * installed skills, its checked-in settings) — but not the operator's
+     * personal configuration. The correct default for a dispatched task.
+     */
+    AgentClientProtocol_HostConfigurationInheritance["APPLICATION_SCOPED"] = "application_scoped";
+    /**
+     * Everything the agent would load if a human had started it by hand,
+     * including operator-level configuration. Honest about what it is: the run
+     * then depends on machine state Wildo neither authored nor recorded, so a run
+     * is not reproducible on another machine.
+     */
+    AgentClientProtocol_HostConfigurationInheritance["HOST_INHERITED"] = "host_inherited";
+})(AgentClientProtocol_HostConfigurationInheritance || (AgentClientProtocol_HostConfigurationInheritance = {}));
+/**
+ * One authored way to start an ACP agent.
+ *
+ * Mirrors the shape a provider's execution profiles have always had: the
+ * spawnable command plus the policy that decides whether it may run at all.
+ */
+export const AgentClientProtocol_ExecutionProfileSchema = z.object({
+    runnerHost: z.enum(AgentClientProtocol_RunnerHost).default(AgentClientProtocol_RunnerHost.BACKEND_SUBPROCESS),
+    /**
+     * The executable that speaks ACP on stdio — OPTIONAL, and normally omitted.
+     *
+     * How to START an agent is the PROVIDER's knowledge: the package, the pinned
+     * version, the launcher. An application that restates it holds a second copy
+     * of a version it does not own, which is how the adapter pin came to be
+     * declared in two places with no mechanical link. Omit these and the provider
+     * contract supplies them; set them only to run an agent the provider does not
+     * describe, and accept owning the version if you do.
+     */
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).optional(),
+    /**
+     * Host environment variables forwarded into the child.
+     *
+     * The runner starts from a minimal identity allowlist and adds only what is
+     * named here. Full inheritance is never available: the process that spawns
+     * the agent holds platform secrets that must not reach it.
+     */
+    inheritedEnvironmentVariables: z.array(z.string().min(1)).optional(),
+    authMode: z.enum(AgentClientProtocol_AuthMode),
+    secretRef: z.string().optional(),
+    secretEnvVarName: z.string().optional(),
+    /**
+     * The environments this profile may run in — REQUIRED, and never widened by
+     * default.
+     *
+     * This is the gate that keeps a workspace-mutating agent out of production.
+     * It is carried here explicitly rather than inherited from anything, because
+     * the equivalent guard on the protocol this replaces was enforced by a single
+     * function that a new transport could have quietly failed to call.
+     */
+    allowedApplicationEnvironments: z.array(z.enum(APPLICATION_ENVIRONMENT)).min(1),
+    /** Optional further narrowing to named platform environments. */
+    allowedPlatformEnvironmentIds: z.array(z.string()).optional(),
+    workingDirectoryPolicy: z.enum(AgentClientProtocol_WorkingDirectoryPolicy).default(AgentClientProtocol_WorkingDirectoryPolicy.WORKSPACE_ROOT),
+    workingDirectoryRelativePath: z.string().optional(),
+    permissionCeiling: z.enum(AgentClientProtocol_PermissionCeiling).default(AgentClientProtocol_PermissionCeiling.PROMPT_ALWAYS),
+    hostConfigurationInheritance: z.enum(AgentClientProtocol_HostConfigurationInheritance).default(AgentClientProtocol_HostConfigurationInheritance.APPLICATION_SCOPED),
+    /**
+     * Wall-clock ceiling for one prompt turn.
+     *
+     * On expiry the runner sends `session/cancel` and waits for the agent to
+     * settle rather than killing the process: ACP defines cancellation as
+     * cooperative, and an agent that is mid-edit should be allowed to stop
+     * cleanly. A hard kill remains the fallback if the agent does not honour it.
+     */
+    turnTimeoutMs: z.number().int().positive().optional(),
+    /**
+     * Ceiling on the bytes of session events this run PERSISTS.
+     *
+     * Semantics are TRUNCATE, not reject — deliberately the opposite of the
+     * output cap this replaces, which killed a run for being talkative after it
+     * had already mutated the workspace. Losing the tail of a transcript is a
+     * reporting loss; losing the run is a work loss.
+     */
+    maximumRecordedEventBytes: z.number().int().positive().optional(),
+    /**
+     * Opaque, agent-specific options passed as `_meta` on `session/new`.
+     *
+     * ACP reserves `_meta` for extensions, and agents use it for options their
+     * own runtime understands and no other agent would. Keeping it opaque is what
+     * keeps the rest of this contract agent-neutral — but it is also unvalidated
+     * and unportable by construction, so anything Wildo needs to GUARANTEE (the
+     * environment gate, the permission ceiling, configuration inheritance) is a
+     * typed field above and never expressed here.
+     */
+    sessionMetaExtensions: z.record(z.string(), z.unknown()).optional(),
+}).strict().superRefine((profile, context) => {
+    if (profile.authMode === AgentClientProtocol_AuthMode.SECRET_REF_ENV_INJECTION && !profile.secretRef) {
+        context.addIssue({
+            code: "custom",
+            message: "`secretRef` is required when `authMode` is `SECRET_REF_ENV_INJECTION`.",
+            path: ["secretRef"],
+        });
+    }
+    if (profile.authMode === AgentClientProtocol_AuthMode.SECRET_REF_ENV_INJECTION && !profile.secretEnvVarName) {
+        context.addIssue({
+            code: "custom",
+            message: "`secretEnvVarName` is required when `authMode` is `SECRET_REF_ENV_INJECTION`.",
+            path: ["secretEnvVarName"],
+        });
+    }
+    // A host-managed or unauthenticated profile carrying a secret binding is a
+    // contradiction the runner would resolve silently — injecting nothing while
+    // the authored configuration claims a credential is in play. Refuse it, so
+    // "this profile injects no secret" is a property of the schema rather than of
+    // a reviewer's reading.
+    if (profile.authMode !== AgentClientProtocol_AuthMode.SECRET_REF_ENV_INJECTION &&
+        (profile.secretRef !== undefined || profile.secretEnvVarName !== undefined)) {
+        context.addIssue({
+            code: "custom",
+            message: "`secretRef`/`secretEnvVarName` are only valid when `authMode` is `SECRET_REF_ENV_INJECTION`.",
+            path: ["secretRef"],
+        });
+    }
+    if (profile.workingDirectoryPolicy === AgentClientProtocol_WorkingDirectoryPolicy.WORKSPACE_RELATIVE_PATH &&
+        !profile.workingDirectoryRelativePath) {
+        context.addIssue({
+            code: "custom",
+            message: "`workingDirectoryRelativePath` is required when using `WORKSPACE_RELATIVE_PATH`.",
+            path: ["workingDirectoryRelativePath"],
+        });
+    }
+    if (profile.workingDirectoryPolicy !== AgentClientProtocol_WorkingDirectoryPolicy.WORKSPACE_RELATIVE_PATH &&
+        profile.workingDirectoryRelativePath !== undefined) {
+        context.addIssue({
+            code: "custom",
+            message: "`workingDirectoryRelativePath` is only valid when using `WORKSPACE_RELATIVE_PATH`.",
+            path: ["workingDirectoryRelativePath"],
+        });
+    }
+    // An UNRESTRICTED ceiling on a profile that may run outside development is
+    // the one combination with no legitimate reading: it authorises an agent to
+    // mutate a non-development workspace with no gate and no record of a decision.
+    if (profile.permissionCeiling === AgentClientProtocol_PermissionCeiling.UNRESTRICTED &&
+        profile.allowedApplicationEnvironments.some((environment) => environment !== APPLICATION_ENVIRONMENT.DEVELOPMENT)) {
+        context.addIssue({
+            code: "custom",
+            message: "`permissionCeiling: UNRESTRICTED` is only valid for a profile restricted to the DEVELOPMENT environment.",
+            path: ["permissionCeiling"],
+        });
+    }
+});
+/**
+ * Transport capability metadata for an ACP-speaking provider.
+ *
+ * Note how little is declared here compared with a one-shot CLI contract, and
+ * why: ACP agents advertise their own capabilities, session modes and available
+ * commands during `initialize` and `session/new`. Re-declaring any of that in
+ * authored configuration would create a second source of truth that drifts the
+ * first time the agent is upgraded. What remains is what the HOST must know
+ * before it opens a connection.
+ */
+export const AgentClientProtocol_ProfileSchema = ExternalProvider_ExchangeProtocol_Profile_BaseSchema.extend({
+    supportedRunnerHosts: z.array(z.enum(AgentClientProtocol_RunnerHost)).default([
+        AgentClientProtocol_RunnerHost.BACKEND_SUBPROCESS,
+    ]),
+    /**
+     * The ACP major versions this provider is known to speak.
+     *
+     * ACP negotiates a single integer at `initialize`: the client offers its
+     * latest, the agent answers with that or its own. This list is what the
+     * runner is willing to accept in that answer — an agent that returns anything
+     * else is refused rather than spoken to hopefully.
+     */
+    supportedProtocolVersions: z.array(z.number().int().positive()).min(1).default([1]),
+    /**
+     * The semantic operations this transport can execute truthfully.
+     *
+     * Kept as strings to avoid a circular runtime import with the operation
+     * family that consumes this protocol — the same reason the CLI contract this
+     * replaces did so.
+     */
+    supportedOperationKeys: z.array(z.string().min(1)).min(1),
+    /**
+     * The semantic models valid on this transport.
+     *
+     * The agent also advertises its own model options per session; this list is
+     * the authored subset an application is willing to select from, and it is
+     * what a requested model is validated against before a session is opened.
+     */
+    supportedModels: z.array(z.string().min(1)).min(1),
+    supportedAuthModes: z.array(z.enum(AgentClientProtocol_AuthMode)).default([
+        AgentClientProtocol_AuthMode.NONE,
+        AgentClientProtocol_AuthMode.HOST_MANAGED,
+        AgentClientProtocol_AuthMode.SECRET_REF_ENV_INJECTION,
+    ]),
+});
+export const AgentClientProtocol_ConfigurationSchema = ExternalProvider_ExchangeProtocol_Configuration_BaseSchema.extend({
+    defaultExecutionProfileRef: z.string().optional(),
+    executionProfiles: z.record(z.string(), AgentClientProtocol_ExecutionProfileSchema),
+}).superRefine((config, context) => {
+    if (config.defaultExecutionProfileRef && !config.executionProfiles[config.defaultExecutionProfileRef]) {
+        context.addIssue({
+            code: "custom",
+            message: "`defaultExecutionProfileRef` must reference an existing execution profile.",
+            path: ["defaultExecutionProfileRef"],
+        });
+    }
+});
+export const AgentClientProtocol_StatusSchema = ExternalProvider_ExchangeProtocol_Status_BaseSchema.extend({
+    protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL),
+    /** The version actually agreed at the last `initialize`, when one succeeded. */
+    negotiatedProtocolVersion: z.number().int().positive().optional(),
+    /**
+     * The agent's self-reported identity from its last `initialize` response.
+     *
+     * Recorded because the agent is an independently released dependency: when a
+     * run starts behaving differently, "which build answered" is the first
+     * question, and it is not answerable from anything Wildo authored.
+     */
+    observedAgentName: z.string().optional(),
+    observedAgentVersion: z.string().optional(),
+});
+//===============================================================
+// Coding-agent operation family
+// --------
+// The semantic operation an ACP session serves. Deliberately NOT an
+// `LLMProvider_OperationKey`: a run that edits a worktree, executes commands
+// and requests authorisation is a different KIND of work from a text
+// completion, and the two enums being disjoint is what lets an agent
+// configuration be narrowed by its operation key alone.
+//===============================================================
+export var CodingAgent_OperationKey;
+(function (CodingAgent_OperationKey) {
+    /** A bounded, scoped change to a workspace, performed by an autonomous agent. */
+    CodingAgent_OperationKey["RUN_CODING_TASK"] = "coding.runCodingTask";
+})(CodingAgent_OperationKey || (CodingAgent_OperationKey = {}));
+/**
+ * Why a prompt turn ended.
+ *
+ * The wire values are ACP's own — this is the thin boundary where the
+ * protocol's vocabulary is translated into a named one Wildo can branch on and
+ * explain. `CANCELLED` in particular must stay distinguishable from `END_TURN`:
+ * a cancelled run's partial change set is a different fact from a completed
+ * run's, and a lane that conflates them reports work as finished that was
+ * interrupted.
+ */
+export var CodingAgent_StopReason;
+(function (CodingAgent_StopReason) {
+    /** The agent finished of its own accord. */
+    CodingAgent_StopReason["END_TURN"] = "end_turn";
+    /** The model's output limit was reached mid-work. */
+    CodingAgent_StopReason["MAX_TOKENS"] = "max_tokens";
+    /** The agent's own per-turn request budget was exhausted. */
+    CodingAgent_StopReason["MAX_TURN_REQUESTS"] = "max_turn_requests";
+    /** The model declined the task. */
+    CodingAgent_StopReason["REFUSAL"] = "refusal";
+    /** The client asked the session to stop, and the agent complied. */
+    CodingAgent_StopReason["CANCELLED"] = "cancelled";
+    /**
+     * WILDO'S OWN marker, not an ACP wire value: the agent reported a stop reason
+     * this protocol version does not define.
+     *
+     * It exists so an unknown value cannot discard evidence. The alternative —
+     * throwing — happens AFTER the turn, i.e. after the workspace has already been
+     * mutated, so it would turn a completed run into an error whose change set
+     * nobody records. Callers must treat this like `CANCELLED`: not a working
+     * result, but a run whose changes are real and must still be captured.
+     */
+    CodingAgent_StopReason["UNRECOGNISED"] = "wildo.unrecognised";
+})(CodingAgent_StopReason || (CodingAgent_StopReason = {}));
+/**
+ * What one coding turn consumed.
+ *
+ * EVERY field is optional, and that is a statement about the protocol rather
+ * than laziness. ACP guarantees only the context-window pair (`used` / `size`)
+ * on its usage notification; token breakdowns and monetary cost are agent
+ * EXTENSIONS — Claude's adapter reports all of them, another agent may report
+ * none. Code that enforces a budget must therefore decide what to do when the
+ * number it wants is absent, and the schema makes that unavoidable rather than
+ * letting a missing value read as zero.
+ *
+ * This is the capability the transport it replaces could not express at all:
+ * a one-shot CLI reported nothing, so budgets were reduced to wall-clock and
+ * run-count proxies.
+ */
+export const CodingAgent_UsageSchema = z.object({
+    /** Context-window tokens in use at the end of the turn (ACP: `usage_update.used`). */
+    contextUsed: z.number().int().nonnegative().optional(),
+    /** Total context window available (ACP: `usage_update.size`). */
+    contextWindowSize: z.number().int().nonnegative().optional(),
+    inputTokens: z.number().int().nonnegative().optional(),
+    outputTokens: z.number().int().nonnegative().optional(),
+    /** Tokens READ from the prompt cache — typically the dominant term for a coding turn. */
+    cachedReadTokens: z.number().int().nonnegative().optional(),
+    /** Tokens WRITTEN to the prompt cache. */
+    cachedWriteTokens: z.number().int().nonnegative().optional(),
+    totalTokens: z.number().int().nonnegative().optional(),
+    /**
+     * Monetary cost of the turn, when the agent reports one.
+     *
+     * Kept as an amount + currency pair rather than a bare number: a budget
+     * denominated in an unstated currency is not a budget. Amount is a plain
+     * number because it arrives that way; anything that ACCUMULATES cost should
+     * round explicitly at its own boundary rather than trusting float addition.
+     */
+    cost: z.object({
+        amount: z.number().nonnegative(),
+        currency: z.string().min(1),
+    }).optional(),
+});
+/**
+ * Transport metadata for a completed coding run.
+ *
+ * Note where this lives: WITH the coding-agent family, not in the LLM
+ * protocol's transport union. A coding run is not an LLM call with a different
+ * wire format, and recording it inside the LLM execution-metadata union would
+ * re-create, one layer down, exactly the mis-modelling this protocol exists to
+ * end.
+ */
+export const AgentClientProtocol_ExecutionTransportMetadataSchema = z.object({
+    protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL),
+    providerRef: z.string(),
+    executionProfileRef: z.string(),
+    model: z.string().optional(),
+    /** The ACP major version agreed at `initialize`. */
+    negotiatedProtocolVersion: z.number().int().positive().optional(),
+    /** The agent's self-reported build — the first question when a run misbehaves. */
+    agentName: z.string().optional(),
+    agentVersion: z.string().optional(),
+    /**
+     * The agent-declared session mode the run actually executed under.
+     *
+     * Recorded verbatim as the agent named it, because it is the agent's
+     * vocabulary and the mapping from Wildo's ceiling is lossy in one direction:
+     * knowing the run was clamped to `PROMPT_ALWAYS` does not tell a later reader
+     * which of the agent's modes that became.
+     */
+    sessionModeId: z.string().optional(),
+    /** The ACP session, retained so a later turn can resume or fork it. */
+    sessionId: z.string().optional(),
+});
+export const CodingAgent_OperationContext_BaseSchema = ExternalProvider_OperationContextSchema.extend({
+    usage: CodingAgent_UsageSchema.optional(),
+    executionTime: z.number().optional(),
+    finishedAt: z.string().optional(),
+    transport: AgentClientProtocol_ExecutionTransportMetadataSchema.optional(),
+});
+// ===============================================================
+// Coding-agent I/O
+// ===============================================================
+/**
+ * Model-selection configuration for a coding agent.
+ *
+ * Deliberately smaller than its LLM sibling, and the omissions are the design.
+ * There is no `temperature`, `topP` or penalty here: those tune a completion,
+ * and an ACP agent is not one — it runs its own inner loop, chooses its own
+ * tools and manages its own sampling. Offering an application knobs the
+ * transport cannot honour would be worse than offering none, because it would
+ * read as configuration and behave as decoration.
+ *
+ * `maxTokens` is likewise absent: a coding run's budget is enforced by the
+ * caller against reported usage after each turn, not requested up front — the
+ * agent decides how many model calls its task needs.
+ */
+export const CodingAgent_OperationModelConfiguration_Schema = z.object({
+    model: z.string(),
+    providerRef: z.string(),
+});
+export const CodingAgent_RunTaskInputSchema = z.object({
+    /**
+     * The rendered task handed to the agent as the turn's prompt.
+     *
+     * A single string on purpose: the caller owns task composition (for
+     * application creation, a typed task contract renders it), and the transport
+     * must not become a second place where task semantics are assembled.
+     */
+    prompt: z.string().min(1),
+    /**
+     * The autonomy this particular run asks for.
+     *
+     * CLAMPED, never honoured blindly: the runner takes the lower of this and the
+     * execution profile's `permissionCeiling`. Absent means the profile's ceiling
+     * — which is itself the safe default — so omitting it can never widen
+     * authority, only leave it where the profile put it.
+     */
+    requestedPermissionCeiling: z.enum(AgentClientProtocol_PermissionCeiling).optional(),
+});
+export const CodingAgent_RunTaskOutputSchema = z.object({
+    /** The agent's closing message — its own account of what it did. */
+    finalMessage: z.string(),
+    stopReason: z.enum(CodingAgent_StopReason),
+    /**
+     * Absolute paths the agent REPORTED touching, from its tool-call stream.
+     *
+     * A claim, not a record. An agent reports what its own tooling surfaces, and
+     * nothing prevents it writing a file it never mentions — measured against
+     * Claude's adapter, file operations happen inside the agent and are reported
+     * afterwards rather than routed through the client. Use this to NARROW an
+     * attribution question; never as the answer. The authoritative record of what
+     * changed is the workspace diff taken around the run.
+     */
+    reportedFileLocations: z.array(z.string()).optional(),
+    /**
+     * How many permission requests the client REFUSED during the turn.
+     *
+     * Recorded because under the strictest ceiling refusal is the NORMAL outcome,
+     * not an exception: without this number a run in which the agent proposed five
+     * changes and was refused every one is indistinguishable from a run in which
+     * it proposed nothing. The agent's own closing message cannot be relied on to
+     * say so.
+     */
+    deniedPermissionCount: z.number().int().nonnegative().optional(),
+    /**
+     * One record per permission request, with the REASON it was decided.
+     *
+     * The count above says HOW MANY were refused; this says WHY, which is the half that makes a
+     * refusal actionable. A run under an UNRESTRICTED ceiling came back with two refusals and no
+     * files written, and nothing recorded could distinguish "the scope predicate refused a path"
+     * from "the agent offered no option the client would select" — opposite defects with an
+     * identical outward appearance, and neither diagnosable without dispatching another agent.
+     *
+     * Deliberately carries no prompt or file CONTENT: the tool kind, the declared paths, the
+     * option kinds offered, and the decision.
+     */
+    permissionDecisions: z.array(z.strictObject({
+        allowed: z.boolean(),
+        reason: z.string(),
+        toolKind: z.string().optional(),
+        locations: z.array(z.string()),
+        offeredOptionKinds: z.array(z.string()),
+    })).optional(),
+    /**
+     * The agent's verbatim stop reason when it was one this version does not
+     * define. Present exactly when `stopReason` is `UNRECOGNISED`.
+     */
+    rawStopReason: z.string().optional(),
+});
+//# sourceMappingURL=agent-client-protocol.external-connectors-models.schemas.js.map