@cat-factory/contracts 0.347.0 → 0.349.0

package/dist/environment-probe.d.ts

@@ -0,0 +1,201 @@
+import * as v from 'valibot';
+import type { BlockType } from './primitives.js';
+/** Which surface a dry run drove: HTTP calls, or a browser. */
+export declare const environmentProbeSurfaceSchema: v.PicklistSchema<["api", "ui"], undefined>;
+export type EnvironmentProbeSurface = v.InferOutput<typeof environmentProbeSurfaceSchema>;
+/**
+ * Which surface a service frame's dry run drives, from the frame's own type.
+ *
+ * A `frontend` frame is a browser job and everything else is a protocol job: there is no third
+ * answer to invent, and no frame type where the choice is genuinely ambiguous: `library` and
+ * `document` frames have no ephemeral-environment provisioning to test, so a dry run never
+ * reaches one. Stated in contracts rather than in the engine because BOTH sides say it to a
+ * human: the backend picks the prober, and the SPA's button has to tell the user which one it is
+ * about to spend money on.
+ */
+export declare function environmentProbeSurfaceFor(type: BlockType): EnvironmentProbeSurface;
+/**
+ * Why one attempted operation did not work, or why the agent never got to attempt it.
+ *
+ * The set is shaped around WHOSE PROBLEM each member is, because that is the whole output of the
+ * diagnostic:
+ *
+ *  - `auth_missing` / `access_unclear` / `endpoint_unknown`: the PLATFORM did not tell the agent
+ *    enough. These are the findings this feature exists to surface: nothing is broken in the
+ *    service, the run would simply have been spent guessing.
+ *  - `auth_rejected` / `bad_request`: the agent knew what to send and the service refused it. A
+ *    credential that is present and rejected is a different fix from one that was never supplied,
+ *    which is why they are not one member.
+ *  - `unreachable` / `timeout` / `server_error`: the ENVIRONMENT is at fault, so the dry run has
+ *    found something the provisioning self-test's `ready` verdict did not.
+ *  - `tooling_missing`: the container had no HTTP client or browser, so the attempt says nothing
+ *    about the environment at all. Its own member for that reason: collapsed into `other` it reads
+ *    as a service that failed.
+ *  - `other`: anything else, with the agent's own detail carrying the specifics.
+ */
+export declare const environmentProbeFailureSchema: v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>;
+export type EnvironmentProbeFailure = v.InferOutput<typeof environmentProbeFailureSchema>;
+/** The failure vocabulary as a list, for a reader that has to enumerate it. */
+export declare const ENVIRONMENT_PROBE_FAILURES: ["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"];
+/** Whether a value is a currently-known failure kind (derived from the picklist's own options). */
+export declare function isEnvironmentProbeFailure(value: unknown): value is EnvironmentProbeFailure;
+/** How one attempted operation turned out. */
+export declare const environmentProbeOutcomeSchema: v.PicklistSchema<["succeeded", "failed", "not_attempted"], undefined>;
+export type EnvironmentProbeOutcome = v.InferOutput<typeof environmentProbeOutcomeSchema>;
+/**
+ * The platform's verdict on a dry run, COMPUTED from the operations the agent reported (see
+ * {@link summarizeEnvironmentProbe}) rather than read off the reply.
+ *
+ *  - `operable`: every operation the agent listed was attempted, every one of them worked, and at
+ *    least one exercised authentication.
+ *  - `partially_operable`: something worked, but not everything, or nothing that worked was
+ *    behind auth, or the agent listed operations it could not even attempt. A public healthcheck
+ *    answering is not evidence that an agent can operate the service, which is why it cannot earn
+ *    `operable` on its own, and neither is a run whose one success sits beside four things the
+ *    agent could not work out how to try.
+ *  - `inoperable`: nothing the agent attempted worked, or it never got to attempt anything.
+ */
+export declare const environmentProbeVerdictSchema: v.PicklistSchema<["operable", "partially_operable", "inoperable"], undefined>;
+export type EnvironmentProbeVerdict = v.InferOutput<typeof environmentProbeVerdictSchema>;
+/** One operation the agent attempted against the live environment. */
+export declare const environmentProbeOperationSchema: v.ObjectSchema<{
+    /** What it was, in the agent's own words ("list projects", "sign in and open the dashboard"). */
+    readonly name: v.StringSchema<undefined>;
+    /** How it was performed: `GET /api/v1/projects`, or the UI path it clicked through. */
+    readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * Whether this operation actually exercised authentication. The one field the verdict turns on:
+     * a dry run whose only successes are anonymous has not shown that an agent can operate the
+     * service, so it never reaches `operable`.
+     */
+    readonly authenticated: v.BooleanSchema<undefined>;
+    readonly outcome: v.PicklistSchema<["succeeded", "failed", "not_attempted"], undefined>;
+    /** Why it did not work. Absent on a success. */
+    readonly failure: v.OptionalSchema<v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>, undefined>;
+    /** The agent's evidence: the status code, the message, what it saw. */
+    readonly detail: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type EnvironmentProbeOperation = v.InferOutput<typeof environmentProbeOperationSchema>;
+/** Something that stopped the dry run as a whole, rather than one operation. */
+export declare const environmentProbeBlockerSchema: v.ObjectSchema<{
+    readonly kind: v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>;
+    readonly detail: v.StringSchema<undefined>;
+}, undefined>;
+export type EnvironmentProbeBlocker = v.InferOutput<typeof environmentProbeBlockerSchema>;
+/** A dry run's report, as persisted on the run row and rendered by the SPA. */
+export declare const environmentProbeReportSchema: v.ObjectSchema<{
+    readonly surface: v.PicklistSchema<["api", "ui"], undefined>;
+    /** Platform-computed; never taken from the reply. */
+    readonly verdict: v.PicklistSchema<["operable", "partially_operable", "inoperable"], undefined>;
+    /** The agent's own account of what it did and what it concluded. */
+    readonly summary: v.StringSchema<undefined>;
+    /** Every operation it attempted (or explicitly did not), in the order it reported them. */
+    readonly operations: v.ArraySchema<v.ObjectSchema<{
+        /** What it was, in the agent's own words ("list projects", "sign in and open the dashboard"). */
+        readonly name: v.StringSchema<undefined>;
+        /** How it was performed: `GET /api/v1/projects`, or the UI path it clicked through. */
+        readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * Whether this operation actually exercised authentication. The one field the verdict turns on:
+         * a dry run whose only successes are anonymous has not shown that an agent can operate the
+         * service, so it never reaches `operable`.
+         */
+        readonly authenticated: v.BooleanSchema<undefined>;
+        readonly outcome: v.PicklistSchema<["succeeded", "failed", "not_attempted"], undefined>;
+        /** Why it did not work. Absent on a success. */
+        readonly failure: v.OptionalSchema<v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>, undefined>;
+        /** The agent's evidence: the status code, the message, what it saw. */
+        readonly detail: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * What the PLATFORM failed to tell it: a credential it needed and had no reference for, an
+     * endpoint it could not discover, a base path it had to guess. The primary product of the
+     * diagnostic, since each entry is a thing to fix before a real run spends a step on it.
+     */
+    readonly missingContext: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    /** Whole-run blockers, distinct from one operation's failure. */
+    readonly blockers: v.ArraySchema<v.ObjectSchema<{
+        readonly kind: v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>;
+        readonly detail: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    /** Platform-computed tallies over `operations`. */
+    readonly attempted: v.NumberSchema<undefined>;
+    readonly succeeded: v.NumberSchema<undefined>;
+    /** How many SUCCESSFUL operations exercised authentication. The verdict's deciding count. */
+    readonly authenticatedSucceeded: v.NumberSchema<undefined>;
+    /**
+     * How many reported operations were dropped AT THE CAP, so a reader never takes a truncated
+     * list for the whole attempt. Absent means nothing was dropped, which is a different fact from
+     * a drop nobody recorded.
+     */
+    readonly operationsOmitted: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    /**
+     * How many reported operations were UNREADABLE (no usable name) and so could not be kept.
+     *
+     * Its own count rather than a second way to spell the one above, because the two send a reader
+     * somewhere different: a cap drop says the agent reported more than the report shows, and an
+     * unreadable entry says the model's reply was malformed. Rendered as "truncated at the cap",
+     * the second one tells an operator their agent did more work than it did.
+     */
+    readonly operationsUnreadable: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    /** The model that produced the report. Absent when the dispatch did not say. */
+    readonly model: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type EnvironmentProbeReport = v.InferOutput<typeof environmentProbeReportSchema>;
+/**
+ * Whether a value is something the coercion below can read anything out of: a plain object.
+ *
+ * Exported because the DISPATCHER asks the same question before it calls the coercion. A reply
+ * that came back as an array, a string or a number has told the platform nothing, and coercing it
+ * yields an empty report the verdict then grades `inoperable`: a finding about the service,
+ * invented out of a malformed reply. The caller that can still say "the agent produced nothing"
+ * has to ask before the shape is flattened, and it has to ask the same question this does.
+ */
+export declare function isEnvironmentProbeReportPayload(value: unknown): value is Record<string, unknown>;
+/**
+ * Tally the operations and derive the verdict: the platform's half of the report.
+ *
+ * `not_attempted` counts towards neither `attempted` nor `succeeded`: an operation the agent
+ * declared it could not even try is a FINDING (it carries the failure kind saying why), not a
+ * failed call, and counting it as attempted would make "nothing was reachable" read as
+ * "everything was tried and failed".
+ *
+ * It does, however, keep the run OFF `operable`, which is the whole reason the counts and the
+ * verdict are computed together here. One authenticated success beside four operations the agent
+ * could not work out how to attempt is the exact shape this diagnostic exists to surface, and
+ * grading it on the attempted ones alone would render "an agent can operate this service" in
+ * green directly above the list of things it could not do.
+ */
+export declare function summarizeEnvironmentProbe(operations: readonly EnvironmentProbeOperation[]): {
+    attempted: number;
+    succeeded: number;
+    authenticatedSucceeded: number;
+    verdict: EnvironmentProbeVerdict;
+};
+/** Scrubs one model-authored string on its way into the report. Identity when none is supplied. */
+type Scrub = (value: string) => string;
+/**
+ * Coerce an agent's raw structured reply into an {@link EnvironmentProbeReport}.
+ *
+ * LENIENT by construction, in the same spirit as the analyst draft's schema: a dry run whose
+ * report was half-malformed still holds the finding somebody has to act on, and discarding the
+ * whole thing would report "the agent produced nothing" for a run that produced plenty. Every
+ * field the reply got wrong degrades to a stated absence rather than to a guess, and every cap
+ * records what it dropped.
+ *
+ * `surface` is supplied by the CALLER, not read from the reply: the platform chose which prober to
+ * dispatch, so a model claiming otherwise would be reporting about a run that did not happen.
+ *
+ * `scrub` is likewise the caller's, because contracts is SPA-visible and the redaction rules live
+ * in kernel. Supplying it is not optional in spirit: this is the COMPOSE site for a body that is
+ * persisted and rendered, the prompt hands the agent the environment's own credential verbatim,
+ * and an agent that pastes its `curl -H "Authorization: Bearer ..."` into an operation's `detail`
+ * is doing the natural thing. The prompt asks it not to, which is guidance, not a boundary.
+ */
+export declare function coerceEnvironmentProbeReport(raw: unknown, context: {
+    surface: EnvironmentProbeSurface;
+    model?: string;
+    scrub?: Scrub;
+}): EnvironmentProbeReport;
+export {};
+//# sourceMappingURL=environment-probe.d.ts.map

package/dist/environment-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-probe.d.ts","sourceRoot":"","sources":["../src/environment-probe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAwBhD,+DAA+D;AAC/D,eAAO,MAAM,6BAA6B,4CAA4B,CAAA;AACtE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,SAAS,GAAG,uBAAuB,CAEnF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,6BAA6B,2LAWxC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,8JAAwC,CAAA;AAE/E,mGAAmG;AACnG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAI1F;AAED,8CAA8C;AAC9C,eAAO,MAAM,6BAA6B,uEAAuD,CAAA;AACjG,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,+EAIxC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF,sEAAsE;AACtE,eAAO,MAAM,+BAA+B;IAC1C,iGAAiG;;IAEjG,uFAAuF;;IAEvF;;;;OAIG;;;IAGH,gDAAgD;;IAEhD,uEAAuE;;aAEvE,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAA;AAE7F,gFAAgF;AAChF,eAAO,MAAM,6BAA6B;;;aAGxC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B;;IAEvC,qDAAqD;;IAErD,oEAAoE;;IAEpE,2FAA2F;;QAhC3F,iGAAiG;;QAEjG,uFAAuF;;QAEvF;;;;WAIG;;;QAGH,gDAAgD;;QAEhD,uEAAuE;;;IAqBvE;;;;OAIG;;IAEH,iEAAiE;;;;;IAEjE,mDAAmD;;;IAGnD,6FAA6F;;IAE7F;;;;OAIG;;IAEH;;;;;;;OAOG;;IAEH,gFAAgF;;aAEhF,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAoCvF;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEhG;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,SAAS,yBAAyB,EAAE,GAAG;IAC3F,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,OAAO,EAAE,uBAAuB,CAAA;CACjC,CAaA;AAED,mGAAmG;AACnG,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;AAItC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE;IAAE,OAAO,EAAE,uBAAuB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3E,sBAAsB,CA0DxB"}

package/dist/environment-probe.js

@@ -0,0 +1,316 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// AGENT DRY RUN: what an agent found when it tried to OPERATE a freshly provisioned
+// ephemeral environment.
+//
+// The provisioning self-test answers "does this service's environment stand up". This answers the
+// question after it: given the environment, the credentials and the repository, can an agent work
+// out what to call, authenticate, and get real work done? That gap is where a pipeline silently
+// burns a whole run today: the deploy is green, the tester reaches the environment, and the agent
+// then has no idea which endpoint carries the operation or which credential opens it. A dry run
+// surfaces it in one diagnostic instead of at the end of a build.
+//
+// The vocabularies here are CLOSED and PERSISTED (they land on an `environment_test_runs` row and
+// on the wire), so both sides read them from this module: the backend coerces a model's reply into
+// the report, and the SPA renders each member with its own translated copy. A reader that meets a
+// value it does not know renders the raw value rather than nothing (the SPA's `PROBE_FAILURE_KEYS`
+// is `te`-guarded for exactly that).
+//
+// The division of labour is the platform's standing rule: the MODEL judges each operation it
+// attempted, and the PLATFORM computes everything derived from those judgements (the counts, the
+// verdict). A model is never asked for a verdict it could then grade itself against.
+// ---------------------------------------------------------------------------
+/** Which surface a dry run drove: HTTP calls, or a browser. */
+export const environmentProbeSurfaceSchema = v.picklist(['api', 'ui']);
+/**
+ * Which surface a service frame's dry run drives, from the frame's own type.
+ *
+ * A `frontend` frame is a browser job and everything else is a protocol job: there is no third
+ * answer to invent, and no frame type where the choice is genuinely ambiguous: `library` and
+ * `document` frames have no ephemeral-environment provisioning to test, so a dry run never
+ * reaches one. Stated in contracts rather than in the engine because BOTH sides say it to a
+ * human: the backend picks the prober, and the SPA's button has to tell the user which one it is
+ * about to spend money on.
+ */
+export function environmentProbeSurfaceFor(type) {
+    return type === 'frontend' ? 'ui' : 'api';
+}
+/**
+ * Why one attempted operation did not work, or why the agent never got to attempt it.
+ *
+ * The set is shaped around WHOSE PROBLEM each member is, because that is the whole output of the
+ * diagnostic:
+ *
+ *  - `auth_missing` / `access_unclear` / `endpoint_unknown`: the PLATFORM did not tell the agent
+ *    enough. These are the findings this feature exists to surface: nothing is broken in the
+ *    service, the run would simply have been spent guessing.
+ *  - `auth_rejected` / `bad_request`: the agent knew what to send and the service refused it. A
+ *    credential that is present and rejected is a different fix from one that was never supplied,
+ *    which is why they are not one member.
+ *  - `unreachable` / `timeout` / `server_error`: the ENVIRONMENT is at fault, so the dry run has
+ *    found something the provisioning self-test's `ready` verdict did not.
+ *  - `tooling_missing`: the container had no HTTP client or browser, so the attempt says nothing
+ *    about the environment at all. Its own member for that reason: collapsed into `other` it reads
+ *    as a service that failed.
+ *  - `other`: anything else, with the agent's own detail carrying the specifics.
+ */
+export const environmentProbeFailureSchema = v.picklist([
+    'auth_missing',
+    'auth_rejected',
+    'access_unclear',
+    'endpoint_unknown',
+    'unreachable',
+    'timeout',
+    'server_error',
+    'bad_request',
+    'tooling_missing',
+    'other',
+]);
+/** The failure vocabulary as a list, for a reader that has to enumerate it. */
+export const ENVIRONMENT_PROBE_FAILURES = environmentProbeFailureSchema.options;
+/** Whether a value is a currently-known failure kind (derived from the picklist's own options). */
+export function isEnvironmentProbeFailure(value) {
+    return (typeof value === 'string' && ENVIRONMENT_PROBE_FAILURES.includes(value));
+}
+/** How one attempted operation turned out. */
+export const environmentProbeOutcomeSchema = v.picklist(['succeeded', 'failed', 'not_attempted']);
+/**
+ * The platform's verdict on a dry run, COMPUTED from the operations the agent reported (see
+ * {@link summarizeEnvironmentProbe}) rather than read off the reply.
+ *
+ *  - `operable`: every operation the agent listed was attempted, every one of them worked, and at
+ *    least one exercised authentication.
+ *  - `partially_operable`: something worked, but not everything, or nothing that worked was
+ *    behind auth, or the agent listed operations it could not even attempt. A public healthcheck
+ *    answering is not evidence that an agent can operate the service, which is why it cannot earn
+ *    `operable` on its own, and neither is a run whose one success sits beside four things the
+ *    agent could not work out how to try.
+ *  - `inoperable`: nothing the agent attempted worked, or it never got to attempt anything.
+ */
+export const environmentProbeVerdictSchema = v.picklist([
+    'operable',
+    'partially_operable',
+    'inoperable',
+]);
+/** One operation the agent attempted against the live environment. */
+export const environmentProbeOperationSchema = v.object({
+    /** What it was, in the agent's own words ("list projects", "sign in and open the dashboard"). */
+    name: v.string(),
+    /** How it was performed: `GET /api/v1/projects`, or the UI path it clicked through. */
+    target: v.optional(v.string()),
+    /**
+     * Whether this operation actually exercised authentication. The one field the verdict turns on:
+     * a dry run whose only successes are anonymous has not shown that an agent can operate the
+     * service, so it never reaches `operable`.
+     */
+    authenticated: v.boolean(),
+    outcome: environmentProbeOutcomeSchema,
+    /** Why it did not work. Absent on a success. */
+    failure: v.optional(environmentProbeFailureSchema),
+    /** The agent's evidence: the status code, the message, what it saw. */
+    detail: v.optional(v.string()),
+});
+/** Something that stopped the dry run as a whole, rather than one operation. */
+export const environmentProbeBlockerSchema = v.object({
+    kind: environmentProbeFailureSchema,
+    detail: v.string(),
+});
+/** A dry run's report, as persisted on the run row and rendered by the SPA. */
+export const environmentProbeReportSchema = v.object({
+    surface: environmentProbeSurfaceSchema,
+    /** Platform-computed; never taken from the reply. */
+    verdict: environmentProbeVerdictSchema,
+    /** The agent's own account of what it did and what it concluded. */
+    summary: v.string(),
+    /** Every operation it attempted (or explicitly did not), in the order it reported them. */
+    operations: v.array(environmentProbeOperationSchema),
+    /**
+     * What the PLATFORM failed to tell it: a credential it needed and had no reference for, an
+     * endpoint it could not discover, a base path it had to guess. The primary product of the
+     * diagnostic, since each entry is a thing to fix before a real run spends a step on it.
+     */
+    missingContext: v.array(v.string()),
+    /** Whole-run blockers, distinct from one operation's failure. */
+    blockers: v.array(environmentProbeBlockerSchema),
+    /** Platform-computed tallies over `operations`. */
+    attempted: v.number(),
+    succeeded: v.number(),
+    /** How many SUCCESSFUL operations exercised authentication. The verdict's deciding count. */
+    authenticatedSucceeded: v.number(),
+    /**
+     * How many reported operations were dropped AT THE CAP, so a reader never takes a truncated
+     * list for the whole attempt. Absent means nothing was dropped, which is a different fact from
+     * a drop nobody recorded.
+     */
+    operationsOmitted: v.optional(v.number()),
+    /**
+     * How many reported operations were UNREADABLE (no usable name) and so could not be kept.
+     *
+     * Its own count rather than a second way to spell the one above, because the two send a reader
+     * somewhere different: a cap drop says the agent reported more than the report shows, and an
+     * unreadable entry says the model's reply was malformed. Rendered as "truncated at the cap",
+     * the second one tells an operator their agent did more work than it did.
+     */
+    operationsUnreadable: v.optional(v.number()),
+    /** The model that produced the report. Absent when the dispatch did not say. */
+    model: v.optional(v.string()),
+});
+/** How much of a model's reply is kept. Every cap here records what it dropped. */
+const CAPS = {
+    operations: 12,
+    name: 160,
+    target: 200,
+    detail: 800,
+    summary: 2000,
+    missingContext: 10,
+    missingContextEntry: 300,
+    blockers: 6,
+};
+/**
+ * One model-authored string, scrubbed and then capped, in that order.
+ *
+ * The order is the platform's standing rule for untrusted text: a scrub applied AFTER a cap can
+ * leave the head of a credential in the kept prefix, and a scrub that runs on the whole value
+ * keeps the prose and the JSON consistent about what was dropped.
+ */
+function text(value, max, scrub) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = scrub(value).trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > max ? `${trimmed.slice(0, max)} [truncated]` : trimmed;
+}
+function outcomeOf(raw) {
+    if (raw === 'succeeded' || raw === 'failed' || raw === 'not_attempted')
+        return raw;
+    // A reply that named no outcome for an operation it listed has told us nothing about it, and
+    // `failed` would attribute a fault the agent never claimed. `not_attempted` is the honest
+    // reading and keeps the entry out of both tallies.
+    return 'not_attempted';
+}
+/**
+ * Whether a value is something the coercion below can read anything out of: a plain object.
+ *
+ * Exported because the DISPATCHER asks the same question before it calls the coercion. A reply
+ * that came back as an array, a string or a number has told the platform nothing, and coercing it
+ * yields an empty report the verdict then grades `inoperable`: a finding about the service,
+ * invented out of a malformed reply. The caller that can still say "the agent produced nothing"
+ * has to ask before the shape is flattened, and it has to ask the same question this does.
+ */
+export function isEnvironmentProbeReportPayload(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function record(value) {
+    return isEnvironmentProbeReportPayload(value) ? value : {};
+}
+function array(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Tally the operations and derive the verdict: the platform's half of the report.
+ *
+ * `not_attempted` counts towards neither `attempted` nor `succeeded`: an operation the agent
+ * declared it could not even try is a FINDING (it carries the failure kind saying why), not a
+ * failed call, and counting it as attempted would make "nothing was reachable" read as
+ * "everything was tried and failed".
+ *
+ * It does, however, keep the run OFF `operable`, which is the whole reason the counts and the
+ * verdict are computed together here. One authenticated success beside four operations the agent
+ * could not work out how to attempt is the exact shape this diagnostic exists to surface, and
+ * grading it on the attempted ones alone would render "an agent can operate this service" in
+ * green directly above the list of things it could not do.
+ */
+export function summarizeEnvironmentProbe(operations) {
+    const attempted = operations.filter((op) => op.outcome !== 'not_attempted').length;
+    const succeeded = operations.filter((op) => op.outcome === 'succeeded').length;
+    const authenticatedSucceeded = operations.filter((op) => op.outcome === 'succeeded' && op.authenticated).length;
+    const verdict = succeeded === 0
+        ? 'inoperable'
+        : succeeded === attempted && attempted === operations.length && authenticatedSucceeded > 0
+            ? 'operable'
+            : 'partially_operable';
+    return { attempted, succeeded, authenticatedSucceeded, verdict };
+}
+const noScrub = (value) => value;
+/**
+ * Coerce an agent's raw structured reply into an {@link EnvironmentProbeReport}.
+ *
+ * LENIENT by construction, in the same spirit as the analyst draft's schema: a dry run whose
+ * report was half-malformed still holds the finding somebody has to act on, and discarding the
+ * whole thing would report "the agent produced nothing" for a run that produced plenty. Every
+ * field the reply got wrong degrades to a stated absence rather than to a guess, and every cap
+ * records what it dropped.
+ *
+ * `surface` is supplied by the CALLER, not read from the reply: the platform chose which prober to
+ * dispatch, so a model claiming otherwise would be reporting about a run that did not happen.
+ *
+ * `scrub` is likewise the caller's, because contracts is SPA-visible and the redaction rules live
+ * in kernel. Supplying it is not optional in spirit: this is the COMPOSE site for a body that is
+ * persisted and rendered, the prompt hands the agent the environment's own credential verbatim,
+ * and an agent that pastes its `curl -H "Authorization: Bearer ..."` into an operation's `detail`
+ * is doing the natural thing. The prompt asks it not to, which is guidance, not a boundary.
+ */
+export function coerceEnvironmentProbeReport(raw, context) {
+    const scrub = context.scrub ?? noScrub;
+    const root = record(raw);
+    const rawOperations = array(root.operations);
+    const operations = [];
+    for (const entry of rawOperations.slice(0, CAPS.operations)) {
+        const op = record(entry);
+        const name = text(op.name, CAPS.name, scrub);
+        if (!name)
+            continue;
+        const target = text(op.target, CAPS.target, scrub);
+        const detail = text(op.detail, CAPS.detail, scrub);
+        const outcome = outcomeOf(op.outcome);
+        const failure = isEnvironmentProbeFailure(op.failure) ? op.failure : undefined;
+        operations.push({
+            name,
+            ...(target ? { target } : {}),
+            authenticated: op.authenticated === true,
+            outcome,
+            // A non-success with no recognised kind still has to say SOMETHING about whose problem it
+            // was, and `other` is the member that says "the detail carries it".
+            ...(outcome === 'succeeded' ? {} : { failure: failure ?? 'other' }),
+            ...(detail ? { detail } : {}),
+        });
+    }
+    const blockers = [];
+    for (const entry of array(root.blockers).slice(0, CAPS.blockers)) {
+        const blocker = record(entry);
+        const detail = text(blocker.detail, CAPS.detail, scrub);
+        if (!detail)
+            continue;
+        blockers.push({
+            kind: isEnvironmentProbeFailure(blocker.kind) ? blocker.kind : 'other',
+            detail,
+        });
+    }
+    const missingContext = [];
+    for (const entry of array(root.missingContext).slice(0, CAPS.missingContext)) {
+        const line = text(entry, CAPS.missingContextEntry, scrub);
+        if (line)
+            missingContext.push(line);
+    }
+    // The two ways an operation the model reported fails to reach the report, counted apart: the
+    // ones past the cap were never looked at, the ones inside it were looked at and had nothing to
+    // identify them by. See the schema's note on why one number for both misreports the first.
+    const overCap = Math.max(0, rawOperations.length - CAPS.operations);
+    const unreadable = Math.max(0, rawOperations.length - overCap - operations.length);
+    return {
+        surface: context.surface,
+        ...summarizeEnvironmentProbe(operations),
+        // An empty summary stays empty rather than being filled with a sentence the model did not
+        // write: the SPA renders the operations and the verdict either way, and inventing prose here
+        // would make a model that returned nothing look like one that reported.
+        summary: text(root.summary, CAPS.summary, scrub) ?? '',
+        operations,
+        missingContext,
+        blockers,
+        ...(overCap > 0 ? { operationsOmitted: overCap } : {}),
+        ...(unreadable > 0 ? { operationsUnreadable: unreadable } : {}),
+        ...(context.model ? { model: context.model } : {}),
+    };
+}
+//# sourceMappingURL=environment-probe.js.map

package/dist/environment-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-probe.js","sourceRoot":"","sources":["../src/environment-probe.ts"],"names":[],"mappings":"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"}

package/dist/environment-test.d.ts

@@ -1,6 +1,23 @@
 import * as v from 'valibot';
-/** The ordered lifecycle stages of an environment-test run. */
-export declare const environmentTestStageSchema: v.PicklistSchema<["creating_branch", "provisioning", "tearing_down", "deleting_branch", "done"], undefined>;
+/**
+ * What a run EXERCISES. Both modes share the whole lifecycle, the cleanup contract and the run
+ * store; the agent mode adds one stage in the middle.
+ *
+ *  - `provision`: the provisioning config alone. Does the environment stand up and come down?
+ *  - `agent-probe`: that, plus the question after it. Handed this environment, its credentials
+ *    and the repository, can an AGENT work out how to operate the service? See
+ *    `environment-probe.ts` for what it reports.
+ */
+export declare const environmentTestModeSchema: v.PicklistSchema<["provision", "agent-probe"], undefined>;
+export type EnvironmentTestMode = v.InferOutput<typeof environmentTestModeSchema>;
+/**
+ * The ordered lifecycle stages of an environment-test run.
+ *
+ * `probing` is reached only in `agent-probe` mode, between a `ready` environment and its
+ * teardown. Every mode still passes through `tearing_down` and `deleting_branch`, because the
+ * always-cleans-up contract is the whole reason a developer is willing to press either button.
+ */
+export declare const environmentTestStageSchema: v.PicklistSchema<["creating_branch", "provisioning", "probing", "tearing_down", "deleting_branch", "done"], undefined>;
 export type EnvironmentTestStage = v.InferOutput<typeof environmentTestStageSchema>;
 /** Terminal-ness of an environment-test run. */
 export declare const environmentTestStatusSchema: v.PicklistSchema<["running", "succeeded", "failed"], undefined>;
@@ -11,9 +28,19 @@ export declare const environmentTestRunSchema: v.ObjectSchema<{
     readonly workspaceId: v.StringSchema<undefined>;
     /** The service frame (board block) whose provisioning config is being tested. */
     readonly blockId: v.StringSchema<undefined>;
+    readonly mode: v.PicklistSchema<["provision", "agent-probe"], undefined>;
+    /**
+     * Terminal-ness of the LIFECYCLE, never the finding.
+     *
+     * `succeeded` means the run did everything it set out to do and left nothing behind, including
+     * an agent dry run whose verdict is `inoperable`, which is a completed diagnostic reporting bad
+     * news. Folding the verdict in here would make the one interesting outcome indistinguishable
+     * from a broken diagnostic, and would leave a real teardown failure with nothing to say. What
+     * the agent FOUND is {@link environmentTestRunSchema.entries.probe}'s `verdict`.
+     */
     readonly status: v.PicklistSchema<["running", "succeeded", "failed"], undefined>;
     /** The stage currently in flight (or `done` when finished successfully). */
-    readonly stage: v.PicklistSchema<["creating_branch", "provisioning", "tearing_down", "deleting_branch", "done"], undefined>;
+    readonly stage: v.PicklistSchema<["creating_branch", "provisioning", "probing", "tearing_down", "deleting_branch", "done"], undefined>;
     /** The temporary branch the run created; null until it is created. */
     readonly branch: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     /** The provisioned environment's URL, when the provider exposed one. */
@@ -21,7 +48,57 @@ export declare const environmentTestRunSchema: v.ObjectSchema<{
     /** One-line failure reason when `status` is `failed`; null otherwise. */
     readonly error: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     /** The stage the run was at when it failed; null unless `status` is `failed`. */
-    readonly failedStage: v.NullableSchema<v.PicklistSchema<["creating_branch", "provisioning", "tearing_down", "deleting_branch", "done"], undefined>, undefined>;
+    readonly failedStage: v.NullableSchema<v.PicklistSchema<["creating_branch", "provisioning", "probing", "tearing_down", "deleting_branch", "done"], undefined>, undefined>;
+    /**
+     * What the dry-run agent reported, once the `probing` stage settled. Null in `provision` mode,
+     * and in `agent-probe` mode until the probe returns, including on a run that FAILED before or
+     * during the probe, where the run's `error` says why there is no report. The two absences are
+     * told apart by `mode` and `failedStage`, never by this field alone.
+     */
+    readonly probe: v.NullableSchema<v.ObjectSchema<{
+        readonly surface: v.PicklistSchema<["api", "ui"], undefined>;
+        readonly verdict: v.PicklistSchema<["operable", "partially_operable", "inoperable"], undefined>;
+        readonly summary: v.StringSchema<undefined>;
+        readonly operations: v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.StringSchema<undefined>;
+            readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly authenticated: v.BooleanSchema<undefined>;
+            readonly outcome: v.PicklistSchema<["succeeded", "failed", "not_attempted"], undefined>;
+            readonly failure: v.OptionalSchema<v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>, undefined>;
+            readonly detail: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        readonly missingContext: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        readonly blockers: v.ArraySchema<v.ObjectSchema<{
+            readonly kind: v.PicklistSchema<["auth_missing", "auth_rejected", "access_unclear", "endpoint_unknown", "unreachable", "timeout", "server_error", "bad_request", "tooling_missing", "other"], undefined>;
+            readonly detail: v.StringSchema<undefined>;
+        }, undefined>, undefined>;
+        readonly attempted: v.NumberSchema<undefined>;
+        readonly succeeded: v.NumberSchema<undefined>;
+        readonly authenticatedSucceeded: v.NumberSchema<undefined>;
+        readonly operationsOmitted: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly operationsUnreadable: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly model: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The dry-run agent's live todo counts while the `probing` stage is in flight, lifted from the
+     * container's own progress exactly as a pipeline step's are.
+     *
+     * Carried on the run rather than left in the container because `probing` is the LONGEST stage
+     * this flow has (a model reading a repository and driving a service, minutes of it) and every
+     * other stage moves the SPA within seconds. With nothing written, no `envTestChanged` event
+     * fires for the whole probe and the card sits frozen on "probing with an agent", which reads
+     * exactly like a wedged run. Null in `provision` mode, before the prober reports any progress,
+     * and once the report has landed.
+     */
+    readonly probeProgress: v.NullableSchema<v.ObjectSchema<{
+        readonly completed: v.NumberSchema<undefined>;
+        readonly inProgress: v.NumberSchema<undefined>;
+        readonly total: v.NumberSchema<undefined>;
+        readonly items: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly label: v.StringSchema<undefined>;
+            readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
+        }, undefined>, undefined>, undefined>;
+    }, undefined>, undefined>;
     readonly createdAt: v.NumberSchema<undefined>;
     readonly updatedAt: v.NumberSchema<undefined>;
 }, undefined>;