@wildo-ai/external-connectors-models 1.1.2 → 1.1.4

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

@@ -99,10 +99,19 @@ 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: PROMPT_ALWAYS < AUTO_ACCEPT_EDITS <
+ * 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.
  */
+/** @wildo_source:part:start acp.permission-ceiling facet:layer:config facet:audience:app-developer */
 export var AgentClientProtocol_PermissionCeiling;
 (function (AgentClientProtocol_PermissionCeiling) {
     /**
@@ -168,9 +177,36 @@ 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.
  *
@@ -204,6 +240,105 @@ export function agentClientProtocolPermissionCeilingRank(ceiling) {
             return 4;
     }
 }
+/**
+ * Whether THIS agent raises `session/request_permission` before it mutates —
+ * the one property that decides whether Wildo's in-flight guards can fire at all.
+ *
+ * # 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
+ * 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
+ * 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
+ * `wildo acp probe`:
+ *
+ *   - Codex (`@agentclientprotocol/codex-acp`, 2026-09-06) raises nothing before
+ *     an in-workspace write in ANY of its three modes, including with an explicit
+ *     `approval_policy = "untrusted"`. Its safety model is a SANDBOX, so an
+ *     in-workspace write is safe by ITS construction and there is nothing to ask
+ *     about. A different architecture, not a defect.
+ *   - OpenCode (1.18.27, 2026-09-04/05) does the same under its DEFAULT
+ *     configuration, and escalates correctly when pointed at a permission
+ *     configuration file. So for that agent the answer is conditional on
+ *     something the HOST supplies.
+ *   - Claude's adapter (`@agentclientprotocol/claude-agent-acp` 0.73.0) raises,
+ *     and both guards fire.
+ *
+ * # Why it is DECLARED rather than inferred, and why it is required
+ *
+ * It cannot be inferred before a run: an agent that never asks and an agent that
+ * had nothing to ask about are indistinguishable from an empty decision list, and
+ * by the time the list is empty the workspace has already been mutated. The
+ * post-run change set remains the authoritative account of what a run touched —
+ * this declaration is what lets the framework say, BEFORE the run, whether that
+ * change set is the only account there will be.
+ *
+ * The provider declares it because the provider is the party that ran the probe.
+ * It is REQUIRED on the runtime contract for the same reason `modelDelivery` is:
+ * this lane has now shipped three safety-relevant fields that were authored,
+ * documented and read by nothing (`hostConfigurationInheritance`, the model
+ * channel, the provider's inherited environment). An author who cannot ship the
+ * gap is better than one who discovers it on a dispatched run.
+ *
+ * It is a CLAIM, never an alibi. The companion still judges each completed run
+ * from that run's OWN permission decisions and change set, so an agent whose
+ * behaviour changes between versions cannot keep a stale, reassuring declaration.
+ */
+/** @wildo_source:part:start acp.permission-escalation facet:layer:config facet:audience:app-developer */
+export var AgentClientProtocol_PermissionEscalationBehaviour;
+(function (AgentClientProtocol_PermissionEscalationBehaviour) {
+    /**
+     * The agent escalates before mutating, so the ceiling and the mutation scope
+     * are both enforceable in flight. The only value under which a ceiling
+     * narrower than UNRESTRICTED means what it says.
+     */
+    AgentClientProtocol_PermissionEscalationBehaviour["RAISES_BEFORE_MUTATION"] = "raises_before_mutation";
+    /**
+     * The agent escalates ONLY when the host points it at a permission
+     * configuration it does not adopt by default.
+     *
+     * The configuration is therefore not hardening — it is the condition under
+     * which the agent may be dispatched with a gate at all, and the variable that
+     * carries the pointer is named on the contract so the dispatch can CHECK that
+     * a profile supplies it instead of trusting a docstring that says it must.
+     */
+    AgentClientProtocol_PermissionEscalationBehaviour["RAISES_ONLY_UNDER_HOST_CONFIGURATION"] = "raises_only_under_host_configuration";
+    /**
+     * The agent never escalates before mutating, under any configuration this
+     * framework can supply. Its own safety model is elsewhere (a sandbox), and
+     * Wildo's in-flight guards are inert for it by construction — the post-run
+     * change set is the only account of what it touched.
+     */
+    AgentClientProtocol_PermissionEscalationBehaviour["NEVER_RAISES"] = "never_raises";
+})(AgentClientProtocol_PermissionEscalationBehaviour || (AgentClientProtocol_PermissionEscalationBehaviour = {}));
+/** @wildo_source:part:end acp.permission-escalation */
+/**
+ * Can Wildo's in-flight permission ceiling and mutation-scope predicate fire for
+ * this agent, as it will actually be started?
+ *
+ * The single definition of that question, so the dispatch's refusal, the run's
+ * recorded metadata and any operator-facing report cannot disagree about it.
+ *
+ * `escalationConfigurationSupplied` answers only the conditional member: it is
+ * whether the composed child environment will actually carry the pointer the
+ * contract names. Deliberately a parameter rather than something this function
+ * reads, because the environment is composed by the dispatch and a predicate
+ * that guessed at it would be a second, quieter answer.
+ */
+export function agentClientProtocolInFlightGuardsCanFire(behaviour, escalationConfigurationSupplied) {
+    switch (behaviour) {
+        case AgentClientProtocol_PermissionEscalationBehaviour.RAISES_BEFORE_MUTATION:
+            return true;
+        case AgentClientProtocol_PermissionEscalationBehaviour.RAISES_ONLY_UNDER_HOST_CONFIGURATION:
+            return escalationConfigurationSupplied;
+        case AgentClientProtocol_PermissionEscalationBehaviour.NEVER_RAISES:
+            return false;
+    }
+}
 /**
  * How much of the HOST MACHINE's agent configuration a session inherits.
  *
@@ -220,6 +355,7 @@ export function agentClientProtocolPermissionCeilingRank(ceiling) {
  * application teaches the agent to use its framework. What it should not
  * silently absorb is whoever happens to be logged in.
  */
+/** @wildo_source:part:start acp.host-configuration-inheritance facet:layer:config facet:audience:app-developer */
 export var AgentClientProtocol_HostConfigurationInheritance;
 (function (AgentClientProtocol_HostConfigurationInheritance) {
     /** No filesystem-sourced agent configuration. The prompt is the whole instruction. */
@@ -238,12 +374,79 @@ 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.
  *
  * 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.
  */
+/** @wildo_source:part:start acp.execution-profile facet:layer:config facet:audience:app-developer */
 export const AgentClientProtocol_ExecutionProfileSchema = z.object({
     runnerHost: z.enum(AgentClientProtocol_RunnerHost).default(AgentClientProtocol_RunnerHost.BACKEND_SUBPROCESS),
     /**
@@ -329,6 +532,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`.
      *
@@ -396,6 +609,7 @@ export const AgentClientProtocol_ExecutionProfileSchema = z.object({
         });
     }
 });
+/** @wildo_source:part:end acp.execution-profile */
 /**
  * Transport capability metadata for an ACP-speaking provider.
  *
@@ -663,6 +877,32 @@ export const AgentClientProtocol_ExecutionTransportMetadataSchema = z.object({
      * which of the agent's modes that became.
      */
     sessionModeId: z.string().optional(),
+    /**
+     * Whether the agent this run started DECLARES that it escalates before
+     * mutating, and whether Wildo's in-flight guards could therefore fire.
+     *
+     * Recorded on the run because the ceiling alone no longer explains the run:
+     * `permissionCeiling: PROMPT_ALWAYS` against an agent that never asks and
+     * against one that always asks describe two completely different runs, and
+     * nothing else in this metadata tells them apart. A later reader looking at a
+     * change set needs to know whether anything stood between the agent and it.
+     *
+     * Optional because the declaration is a provider fact and a run recorded
+     * before this field existed genuinely has no answer — absence must not read as
+     * `false`, which would assert an unbound run that may have been fully bound.
+     */
+    permissionEscalation: z.enum(AgentClientProtocol_PermissionEscalationBehaviour).optional(),
+    /**
+     * The resolved answer for THIS run, from
+     * {@link agentClientProtocolInFlightGuardsCanFire} — the declared behaviour
+     * combined with whether the composed environment actually supplied the
+     * configuration a conditionally-escalating agent needs.
+     *
+     * Kept beside the behaviour rather than derived by each reader, because the
+     * conditional member cannot be resolved from the behaviour alone and a reader
+     * that tried would answer `true` for an agent that was dispatched unconfigured.
+     */
+    inFlightPermissionGuardsCanFire: z.boolean().optional(),
     /** The ACP session, retained so a later turn can resume or fork it. */
     sessionId: z.string().optional(),
 });
@@ -789,4 +1029,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