@wildo-ai/external-connectors-models 1.1.3 → 1.1.5

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

@@ -1,6 +1,6 @@
 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";
+import { APPLICATION_ENVIRONMENT, ExternalProvider_ExchangeProtocol_Configuration_BaseSchema, ExternalProvider_ExchangeProtocol_Kind, } from "../core/commons.external-connectors-models.schemas.js";
 //===============================================================
 // Agent Client Protocol (ACP)
 // --------
@@ -99,17 +99,9 @@ export var AgentClientProtocol_WorkingDirectoryPolicy;
  * 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 over all FIVE members: PROMPT_ALWAYS <
- * AUTO_ACCEPT_READS < AUTO_ACCEPT_EDITS < AUTO_ACCEPT_READS_AND_EDITS <
- * UNRESTRICTED. Compare through {@link agentClientProtocolPermissionCeilingRank}
- * rather than by string, so the ordering has one definition.
- *
- * Read that order as a CLAMP — how much is pre-approved without a human — and never
- * as containment. The ceilings are kind-SETS and are deliberately not nested:
- * AUTO_ACCEPT_EDITS outranks AUTO_ACCEPT_READS and still refuses `fetch`, which is
- * exactly why AUTO_ACCEPT_READS_AND_EDITS had to be added rather than being implied
- * by the higher rank. Each member's own docstring states the set it admits, and the
- * rank function carries the full argument for why containment is the wrong reading.
+ * Policies describe admitted tool-kind sets, not nested levels. Invocation overrides
+ * intersect those sets with the profile: READS and EDITS have an empty intersection.
+ * The rank helper is a presentation ordering only and must not select authority.
  */
 /** @wildo_source:part:start acp.permission-ceiling facet:layer:config facet:audience:app-developer */
 export var AgentClientProtocol_PermissionCeiling;
@@ -177,28 +169,42 @@ export var AgentClientProtocol_PermissionCeiling;
      * can fetch anything and write only its evidence directory.
      */
     AgentClientProtocol_PermissionCeiling["AUTO_ACCEPT_READS_AND_EDITS"] = "auto_accept_reads_and_edits";
-    /** No permission gate. Reserve for a disposable or isolated workspace. */
+    /**
+     * No permission gate: every tool kind is pre-approved, `execute` and the unclassified `other`
+     * included. Reserve for a disposable or isolated workspace.
+     *
+     * **This member also removes the task's mutation scope for shell commands, and that is a property
+     * of shell commands rather than of this value.** The scope predicate runs AFTER the ceiling and
+     * denies any location the task did not authorise even here — so declared file EDITS stay confined.
+     * But it decides on the `locations` a permission request carries, and a shell command carries
+     * NONE, because what a command writes is not derivable from the command string. Every ceiling
+     * below this one refuses `execute` outright, so the empty-location case never reaches the
+     * predicate; under this one it does, and `locations.some(...)` over an empty array is vacuously
+     * satisfied. A mutating command therefore reaches the workspace inside a complete, well-formed
+     * permission record showing it was allowed.
+     *
+     * Not closable by deriving a scope from the command: any parse is defeated by `sh -c "$CMD"` or a
+     * redirect through a substituted path, and an invented scope that can be walked around is worse
+     * than a stated absence. So the residual exposure under this member is exactly "shell commands are
+     * unbounded", the answer to it is git plus the post-run change set, and the companion WARNS on
+     * every run whose mutation followed a permitted act that declared no location — which is how it
+     * stops being invisible. Author this member to state that plainly; do not author it expecting the
+     * mutation scope to hold for commands.
+     *
+     * Note this is a DIFFERENT hole from an agent that never asks (see
+     * {@link AgentClientProtocol_PermissionEscalationBehaviour}): that one costs you both guards for
+     * every act, and dispatch refuses a narrower ceiling against such an agent. This one costs you the
+     * scope guard for one act kind, against a fully compliant agent.
+     */
     AgentClientProtocol_PermissionCeiling["UNRESTRICTED"] = "unrestricted";
 })(AgentClientProtocol_PermissionCeiling || (AgentClientProtocol_PermissionCeiling = {}));
 /** @wildo_source:part:end acp.permission-ceiling */
 /**
- * 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.
+ * Stable presentation order for {@link AgentClientProtocol_PermissionCeiling}.
+ *
+ * Never use this rank to authorize or clamp a request. READS and EDITS admit disjoint
+ * tool-kind sets; choosing the numerically lower one can grant operations forbidden
+ * by the profile. Dispatch computes their intersection instead.
  */
 export function agentClientProtocolPermissionCeilingRank(ceiling) {
     switch (ceiling) {
@@ -220,11 +226,12 @@ export function agentClientProtocolPermissionCeilingRank(ceiling) {
  *
  * # Why a permission ceiling needs this to mean anything
  *
- * Both of Wildo's in-flight controls are enforced in the CLIENT's ANSWER to a
+ * For agent-owned I/O, Wildo's in-flight controls are enforced in the CLIENT's ANSWER to a
  * permission request: {@link AgentClientProtocol_PermissionCeiling} decides the
  * tool KIND, and the dispatch's location predicate decides the PATHS. Neither is
  * a sandbox, an interposed filesystem, or a syscall filter — they are answers.
- * So an agent that writes without asking is bound by neither, and the ceiling
+ * Client-hosted writes independently check both controls. An agent doing its OWN I/O
+ * without asking is bound by neither, and the ceiling
  * an application authored is a LABEL rather than a guarantee.
  *
  * That is not hypothetical and it is not a fault in the agents. MEASURED with
@@ -349,6 +356,71 @@ export var AgentClientProtocol_HostConfigurationInheritance;
     AgentClientProtocol_HostConfigurationInheritance["HOST_INHERITED"] = "host_inherited";
 })(AgentClientProtocol_HostConfigurationInheritance || (AgentClientProtocol_HostConfigurationInheritance = {}));
 /** @wildo_source:part:end acp.host-configuration-inheritance */
+/** @wildo_source:part:start acp.execution-profile facet:layer:config facet:audience:app-developer */
+/**
+ * WHERE a coding run's content actually goes, per MODEL (issue #308, join 2).
+ *
+ * An ACP coding session sends the composed task prompt, retrieved context and — through the agent's
+ * own file reads — the application's SOURCE CODE to the selected model vendor. For an application
+ * built with Wildo that can include the customer's domain model, schemas, seed data shapes and
+ * business rules. So the destination is a processor-register fact, not a runtime detail.
+ *
+ * ## Why this is per MODEL and not per provider
+ *
+ * A generalist agent routes to several vendors, so its OWN legal identity is not the identity of the
+ * vendor a given run reaches: OpenCode is a binary on the host, and the same profile can send code to
+ * Anthropic or to OpenAI depending on one model id. A per-provider declaration structurally cannot
+ * express that — it would name the agent's publisher as the recipient of code the publisher never
+ * receives, which is false in the direction a reader cannot check.
+ *
+ * ## Why it lives on the EXECUTION PROFILE
+ *
+ * The profile is already where an application authors the policy it owns, and the model is selected at
+ * dispatch time against that profile. The competing home — `providerComplianceChoices`, where every
+ * other compliance answer lives — cannot carry it: that surface is keyed by provider ref and has one
+ * entry per provider, which is exactly the shape that cannot say "per model".
+ *
+ * `ApplicationProviderComplianceChoice` warns against putting a compliance answer somewhere "nothing
+ * can read it without knowing the provider", and `providerConfigurations` is genuinely an opaque
+ * `Record<string, unknown>` bag. That objection is answered rather than ignored:
+ * {@link readCodingModelDestinations} is the named reader, exported beside this schema, and the
+ * compliance renderer calls it instead of reaching into the bag and guessing a shape. The hazard the
+ * warning names is a fact nobody can FIND; a named reader is what removes it.
+ */
+export const AgentClientProtocol_ModelDestinationSchema = z.object({
+    /**
+     * The legal entity that receives the code — the model vendor, NOT the agent's publisher.
+     *
+     * Required, because a destination that cannot be named is not a destination a processor register can
+     * state. There is no framework default: the framework does not know which account an operator
+     * authorised, and inventing one would publish a recipient nobody declared.
+     */
+    vendorLegalEntityName: z.string().trim().min(1),
+    /**
+     * Where that vendor processes it.
+     *
+     * Open strings for the same reason `ProviderComplianceProfile.processingRegions` uses them: these
+     * are the VENDOR's own labels and a closed enum here would be this repository inventing a
+     * vocabulary it does not own.
+     */
+    processingRegions: z.array(z.string().trim().min(1)).min(1),
+    /**
+     * The INTERMEDIARY, when the run reaches the vendor through one (issue #308, join 3).
+     *
+     * A hosted gateway — OpenCode Zen, an Anthropic-compatible proxy reached through a base-URL
+     * override — receives the content before the vendor does. It is therefore its own processor and must
+     * appear as a sub-processor DISTINCT from the vendor behind it: naming only the vendor understates
+     * the chain by one party, and naming only the gateway understates it by the other.
+     *
+     * Absent means the run reaches the vendor directly. That is a claim, not a silence — declaring a
+     * destination at all is what makes it one.
+     */
+    gateway: z.object({
+        legalEntityName: z.string().trim().min(1),
+        processingRegions: z.array(z.string().trim().min(1)).min(1),
+    }).optional(),
+}).strict();
+/** @wildo_source:part:end acp.execution-profile */
 /**
  * One authored way to start an ACP agent.
  *
@@ -441,6 +513,16 @@ export const AgentClientProtocol_ExecutionProfileSchema = z.object({
      * reporting loss; losing the run is a work loss.
      */
     maximumRecordedEventBytes: z.number().int().positive().optional(),
+    /**
+     * Per-model processing destinations — see {@link AgentClientProtocol_ModelDestinationSchema}.
+     *
+     * OPTIONAL, and its absence is REPORTED rather than refused. A stale framework region list must not
+     * be able to brick an application build, and an operator who has just moved a vendor should be able
+     * to say so before the framework catches up — the same warn-do-not-block posture
+     * `appAssertedProcessingRegions` already takes for provider regions. The compliance brief names a
+     * coding profile that declares none, so the gap is visible without being fatal.
+     */
+    modelDestinations: z.record(z.string().trim().min(1), AgentClientProtocol_ModelDestinationSchema).optional(),
     /**
      * Opaque, agent-specific options passed as `_meta` on `session/new`.
      *
@@ -509,51 +591,6 @@ export const AgentClientProtocol_ExecutionProfileSchema = z.object({
     }
 });
 /** @wildo_source:part:end acp.execution-profile */
-/**
- * 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),
@@ -566,20 +603,6 @@ export const AgentClientProtocol_ConfigurationSchema = ExternalProvider_Exchange
         });
     }
 });
-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
 // --------
@@ -705,7 +728,13 @@ export const CodingAgent_SessionSuspensionSchema = z.strictObject({
      * context — a degradation the caller should surface, not hide.
      */
     resumable: z.boolean(),
-    /** When the parked child process will be closed (ISO timestamp). */
+    /**
+     * An INFORMATIONAL freshness bound for the question (ISO timestamp), surfaced to the operator —
+     * never a reaping deadline. No child process is held open while a run is parked (see
+     * `awaitingInputTtlMs`), so there is nothing that closes at this instant. It said "when the parked
+     * child process will be closed" until 2026-09-24, contradicting the contract above it, and a host
+     * read it that way and aborted answerable questions at boot (#1533).
+     */
     parkedUntil: z.string().optional(),
 });
 /**
@@ -844,8 +873,8 @@ export const CodingAgent_RunTaskInputSchema = z.object({
     /**
      * 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
+     * INTERSECTED, never honoured blindly: dispatch admits only tool kinds shared by
+     * this policy 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.
      */
@@ -928,4 +957,69 @@ export const CodingAgent_RunTaskOutputSchema = z.object({
      */
     suspension: CodingAgent_SessionSuspensionSchema.optional(),
 });
+/**
+ * Read per-model coding destinations out of an application's provider configurations.
+ *
+ * ## Why this function exists at all
+ *
+ * `providerConfigurations` is `Record<string, Record<string, unknown>>` — genuinely opaque, and
+ * `ApplicationProviderComplianceChoice` warns for that reason that "a compliance answer must not live
+ * somewhere nothing can read it without knowing the provider". The destination has to live there
+ * anyway (it is per MODEL, and no per-provider surface can hold it), so the objection is answered by
+ * making the reader NAMED and exported beside the schema instead of leaving each consumer to reach in
+ * and guess a shape. A compliance renderer calls this; it never parses the bag.
+ *
+ * ## What it does with malformed input
+ *
+ * SKIPS it, silently, and this is deliberate rather than lax. The function's job is to report what an
+ * application declared, and it is called from a compliance BRIEF — a lane that must not fail because
+ * one provider's opaque configuration has an unexpected shape. A profile whose destinations do not
+ * parse contributes nothing and therefore surfaces in `profilesWithoutDestinations`, which is the
+ * honest reading: nothing usable was declared.
+ *
+ * Nothing is lost by that leniency, because a malformed profile is ALREADY refused where it matters:
+ * `getAgentClientProtocolExecutionProfile` parses every profile through
+ * {@link AgentClientProtocol_ExecutionProfileSchema} when a run resolves one, and throws
+ * `ErrorType.CONFIGURATION` naming the provider and profile. So a bad destination fails the CODING RUN
+ * loudly, with an author present, while the compliance brief still reports the other twenty providers.
+ * Two surfaces, two correct answers — and note that the profile schema is `.strict()`, so before
+ * `modelDestinations` existed as a declared field an application COULD NOT have authored it at all.
+ */
+export function readCodingModelDestinations(
+/*
+ * `unknown` per value, not `Record<string, unknown>`, because that is what the bag genuinely is at
+ * every consumer — `ProviderConfigurations` types each entry as optional and the companion's own
+ * local view types it as `unknown`. Declaring a narrower parameter would push a cast onto every
+ * caller, which is how a reader written to STOP callers guessing a shape starts making them assert
+ * one.
+ */
+providerConfigurations) {
+    const destinations = [];
+    const profilesWithoutDestinations = [];
+    for (const providerRef of Object.keys(providerConfigurations).sort()) {
+        const providerConfiguration = providerConfigurations[providerRef];
+        if (providerConfiguration === null || typeof providerConfiguration !== 'object')
+            continue;
+        const acpConfiguration = providerConfiguration[ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL];
+        if (acpConfiguration === null || typeof acpConfiguration !== 'object')
+            continue;
+        const profiles = acpConfiguration.executionProfiles;
+        if (profiles === null || typeof profiles !== 'object')
+            continue;
+        for (const executionProfileRef of Object.keys(profiles).sort()) {
+            const profile = profiles[executionProfileRef];
+            const declared = profile?.modelDestinations;
+            const parsed = z.record(z.string().trim().min(1), AgentClientProtocol_ModelDestinationSchema)
+                .safeParse(declared);
+            if (!parsed.success || Object.keys(parsed.data).length === 0) {
+                profilesWithoutDestinations.push({ providerRef, executionProfileRef });
+                continue;
+            }
+            for (const model of Object.keys(parsed.data).sort()) {
+                destinations.push({ providerRef, executionProfileRef, model, destination: parsed.data[model] });
+            }
+        }
+    }
+    return { destinations, profilesWithoutDestinations };
+}
 //# sourceMappingURL=agent-client-protocol.external-connectors-models.schemas.js.map