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

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) {
     /**
@@ -150,9 +159,28 @@ export var AgentClientProtocol_PermissionCeiling;
      * outright, and {@link AUTO_ACCEPT_EDITS} admits precisely the inverse of what research needs.
      */
     AgentClientProtocol_PermissionCeiling["AUTO_ACCEPT_READS"] = "auto_accept_reads";
+    /**
+     * The non-mutating kinds AND the file-mutating kinds are auto-accepted; `execute` and the
+     * unclassified `other` must still be answered — and with no human at the other end, that means
+     * denied.
+     *
+     * Added 2026-09-04 for the research-agent evidence store, and MEASURED before it existed rather
+     * than after: switching the research profile from {@link AUTO_ACCEPT_READS} to
+     * {@link AUTO_ACCEPT_EDITS} — so the agent could persist findings to disk — silently inverted the
+     * lane's whole posture, because the ceilings are kind-SETS, not nested ranks: a live compliance
+     * run spent two rounds with every WebFetch/WebSearch refused, and its only output was a store
+     * note titled "NO EVIDENCE COLLECTED". A lane that both reads the world and persists what it
+     * read needs this member; neither existing set contains the other.
+     *
+     * The confinement story is unchanged: this ceiling decides KINDS, and the dispatch's location
+     * predicate still decides PATHS — a research profile on this ceiling with a store-only predicate
+     * 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. */
     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.
  *
@@ -180,8 +208,109 @@ export function agentClientProtocolPermissionCeilingRank(ceiling) {
             return 1;
         case AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_EDITS:
             return 2;
-        case AgentClientProtocol_PermissionCeiling.UNRESTRICTED:
+        case AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS_AND_EDITS:
             return 3;
+        case AgentClientProtocol_PermissionCeiling.UNRESTRICTED:
+            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;
     }
 }
 /**
@@ -200,6 +329,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. */
@@ -218,12 +348,14 @@ export var AgentClientProtocol_HostConfigurationInheritance;
      */
     AgentClientProtocol_HostConfigurationInheritance["HOST_INHERITED"] = "host_inherited";
 })(AgentClientProtocol_HostConfigurationInheritance || (AgentClientProtocol_HostConfigurationInheritance = {}));
+/** @wildo_source:part:end acp.host-configuration-inheritance */
 /**
  * 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),
     /**
@@ -274,6 +406,32 @@ export const AgentClientProtocol_ExecutionProfileSchema = z.object({
      * cleanly. A hard kill remains the fallback if the agent does not honour it.
      */
     turnTimeoutMs: z.number().int().positive().optional(),
+    /**
+     * How many times one invocation may AUTO-CONTINUE the agent after it ends a
+     * turn with a self-imposed pause ("shall I continue?").
+     *
+     * The autonomous lane's answer to the agent's own checkpoint reflex: a turn
+     * classified as SELF_PAUSE is re-prompted to continue on the same session
+     * rather than read as a finished result. Bounded because an agent that pauses
+     * forever must eventually be settled rather than looped — on exhaustion the
+     * run settles with what it has, recorded as such. Zero disables continuation
+     * entirely (every END_TURN is final, the pre-2026-09 behaviour).
+     */
+    maxAutoContinuations: z.number().int().nonnegative().default(8),
+    /**
+     * How long an operator answer to a parked question stays valid — the deadline
+     * stamped onto the suspension as `parkedUntil`.
+     *
+     * The parked run does NOT hold a live agent process open for this window: the
+     * child is closed the moment the run parks (holding it would occupy the lane's
+     * single-flight slot while an operator who may never answer decides). Because
+     * the agent persists the session on disk, a later answer re-enters it through
+     * `session/load` — so this is an informational freshness bound the host and UX
+     * surface, not a timer that reaps a process. It applies only when the agent
+     * advertises `loadSession`; otherwise the question is real but unanswerable
+     * on the same session, and `resumable` says so.
+     */
+    awaitingInputTtlMs: z.number().int().positive().default(900_000),
     /**
      * Ceiling on the bytes of session events this run PERSISTS.
      *
@@ -350,6 +508,7 @@ export const AgentClientProtocol_ExecutionProfileSchema = z.object({
         });
     }
 });
+/** @wildo_source:part:end acp.execution-profile */
 /**
  * Transport capability metadata for an ACP-speaking provider.
  *
@@ -469,6 +628,86 @@ export var CodingAgent_StopReason;
      */
     CodingAgent_StopReason["UNRECOGNISED"] = "wildo.unrecognised";
 })(CodingAgent_StopReason || (CodingAgent_StopReason = {}));
+/**
+ * What an END_TURN actually meant — the judgment the turn ladder branches on.
+ *
+ * ACP delivers every voluntary stop identically: `end_turn` plus whatever the
+ * agent last said. Three very different situations arrive in that one shape,
+ * and only reading the message tells them apart, which is why this is decided
+ * by an auxiliary LLM classification rather than by a heuristic on the text:
+ * a regex that recognises "shall I continue?" is an invented vocabulary for
+ * someone else's prose.
+ */
+export var CodingAgent_EndOfTurnClassification;
+(function (CodingAgent_EndOfTurnClassification) {
+    /** The agent finished the task; the turn is a final result. */
+    CodingAgent_EndOfTurnClassification["TASK_COMPLETE"] = "task_complete";
+    /**
+     * The agent paused of its own accord — "next?", "want me to proceed?" — a
+     * checkpoint reflex, not a need. The ladder answers it with the continuation
+     * prompt instead of surfacing it, because at this level those checkpoints are
+     * deliberately avoided (autonomy directive, 2026-09-04).
+     */
+    CodingAgent_EndOfTurnClassification["SELF_PAUSE"] = "self_pause";
+    /**
+     * The agent asked something only the caller can answer — a real decision, a
+     * missing credential, an ambiguity in the task. The session parks and the
+     * question is surfaced; auto-continuing would make the agent answer itself.
+     */
+    CodingAgent_EndOfTurnClassification["NEEDS_INPUT"] = "needs_input";
+    /**
+     * The classifier itself failed or timed out. FAILS OPEN to settlement: the
+     * turn is treated as TASK_COMPLETE, because an auxiliary call must never hang
+     * the autonomous lane or discard a mutated workspace — but the failure is
+     * recorded as this value rather than laundered into a confident judgment.
+     */
+    CodingAgent_EndOfTurnClassification["CLASSIFIER_UNAVAILABLE"] = "classifier_unavailable";
+})(CodingAgent_EndOfTurnClassification || (CodingAgent_EndOfTurnClassification = {}));
+/**
+ * One auto-continuation the turn ladder performed, recorded per turn boundary.
+ *
+ * Kept as a record rather than a counter for the same reason permission
+ * decisions are: a run that continued five times and one that never paused are
+ * different runs, and the difference is diagnosable only if each boundary says
+ * what was classified and what was sent back.
+ */
+export const CodingAgent_ContinuationRecordSchema = z.strictObject({
+    /** 1-based index of the turn that ENDED at this boundary. */
+    turnIndex: z.number().int().positive(),
+    classification: z.enum(CodingAgent_EndOfTurnClassification),
+    /**
+     * The tail of the agent's end-of-turn message the classification was made
+     * from. A bounded excerpt, not the transcript — enough to audit the judgment.
+     */
+    agentMessageTail: z.string().optional(),
+});
+/**
+ * A run that STOPPED WITHOUT FINISHING because the agent needs an answer.
+ *
+ * The ACP sibling of `AgentApprovalSuspension` on the LLM transport: the
+ * invocation returns, but its output must not be read as a completed result —
+ * `suspension` present means the final message is a QUESTION. The caller
+ * surfaces the question, and the answer re-enters the SAME session:
+ * `resumable: true` promises the agent advertised `loadSession`, so the session
+ * survives the child process and even a host restart.
+ */
+export const CodingAgent_SessionSuspensionSchema = z.strictObject({
+    /** The ACP session to resume with the answer. */
+    sessionId: z.string().min(1),
+    /** The agent's question, verbatim — its end-of-turn message. */
+    question: z.string().min(1),
+    /** 1-based turn the session parked after. */
+    turnIndex: z.number().int().positive(),
+    /**
+     * Whether the session can be re-entered after the agent process is gone.
+     * False when the agent does not advertise `loadSession`: the question is
+     * still real, but answering it starts a NEW session that must restate task
+     * context — a degradation the caller should surface, not hide.
+     */
+    resumable: z.boolean(),
+    /** When the parked child process will be closed (ISO timestamp). */
+    parkedUntil: z.string().optional(),
+});
 /**
  * What one coding turn consumed.
  *
@@ -537,6 +776,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(),
 });
@@ -585,6 +850,16 @@ export const CodingAgent_RunTaskInputSchema = z.object({
      * authority, only leave it where the profile put it.
      */
     requestedPermissionCeiling: z.enum(AgentClientProtocol_PermissionCeiling).optional(),
+    /**
+     * Present when this run ANSWERS a parked session rather than starting a task.
+     *
+     * Carries the `sessionId` from a prior run's `suspension`; the transport
+     * re-enters that session via `session/load` and delivers `prompt` (the
+     * answer) as the next turn. Refused — not degraded — when the agent does not
+     * advertise `loadSession`: silently starting a fresh session would present a
+     * context-less answer as a continuation.
+     */
+    continuationOfSessionId: z.string().min(1).optional(),
 });
 export const CodingAgent_RunTaskOutputSchema = z.object({
     /** The agent's closing message — its own account of what it did. */
@@ -635,5 +910,22 @@ export const CodingAgent_RunTaskOutputSchema = z.object({
      * define. Present exactly when `stopReason` is `UNRECOGNISED`.
      */
     rawStopReason: z.string().optional(),
+    /**
+     * How many prompt turns this invocation drove on the session. Absent means
+     * one — the single-turn shape every pre-ladder consumer already assumes.
+     */
+    turnCount: z.number().int().positive().optional(),
+    /**
+     * One record per turn boundary the ladder judged — auto-continues, the park,
+     * the settlement. See {@link CodingAgent_ContinuationRecordSchema}.
+     */
+    continuations: z.array(CodingAgent_ContinuationRecordSchema).optional(),
+    /**
+     * Present when the run PARKED on a genuine question instead of finishing.
+     * `finalMessage` is then the QUESTION, and `stopReason` is the wire-true
+     * `END_TURN` — this field is what stops that reading as a completed result.
+     * Callers that ignore it record work as done that is waiting on an answer.
+     */
+    suspension: CodingAgent_SessionSuspensionSchema.optional(),
 });
 //# sourceMappingURL=agent-client-protocol.external-connectors-models.schemas.js.map