@xenosystem/agent-interface-core 0.1.3

package/LICENSE

@@ -0,0 +1,67 @@
+XENO Agent — Proprietary Software License
+Copyright © 2026 XENO Corporation. All rights reserved.
+
+This software, including its source code, compiled binaries, published packages,
+assets, and accompanying documentation (collectively, the "Software"), is the
+proprietary and confidential property of XENO Corporation ("XENO"). The Software
+is licensed for use, not sold, and no title to or ownership of the Software is
+transferred to any user.
+
+1. GRANT OF USE
+   Subject to a separate written agreement and/or the terms of service published
+   at https://xenostudio.ai, XENO grants the end user a limited, non-exclusive,
+   non-transferable, revocable license to install and use the Software for its
+   intended purpose. The standalone desktop application ("the Agent") may be used
+   locally at no charge; connected platform features — hosted agent runs, model
+   inference, credits, and account services — are governed by the applicable
+   subscription and the XENO terms of service.
+
+2. PACKAGE DISTRIBUTION
+   The `@xeno-corporation/xeno-agent-interface-*` and
+   `@xeno-corporation/xeno-agents-client` packages are published to a PRIVATE
+   registry and are licensed for use solely by XENO products and by parties
+   holding a separate written agreement with XENO. Access credentials to that
+   registry do not grant redistribution rights. Publication of any package in
+   this repository to a public registry is prohibited without written
+   authorization from XENO.
+
+3. RESTRICTIONS
+   Except to the extent expressly permitted by applicable law or by a separate
+   written agreement with XENO, you may NOT: (a) copy, redistribute, sell, rent,
+   lease, sublicense, or otherwise transfer the Software; (b) modify, adapt,
+   translate, or create derivative works of the Software; (c) reverse-engineer,
+   decompile, or disassemble the Software, or attempt to derive its source code;
+   (d) remove, obscure, or alter any proprietary notices; or (e) use the Software
+   to build a competing product.
+
+4. RESERVATION OF RIGHTS
+   All rights not expressly granted are reserved by XENO Corporation. The Software
+   is protected by copyright and other intellectual-property laws and treaties.
+
+5. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THE
+   SOFTWARE EXECUTES AGENT-DIRECTED OPERATIONS AGAINST A USER-SELECTED WORKSPACE,
+   INCLUDING FILE AND PROCESS ACTIONS; THE USER IS RESPONSIBLE FOR THE WORKSPACES
+   AND PERMISSIONS THEY GRANT IT.
+
+6. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL XENO CORPORATION BE
+   LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+   DAMAGES, OR ANY LOSS OF PROFITS OR DATA, ARISING FROM OR RELATED TO THE USE OF
+   OR INABILITY TO USE THE SOFTWARE.
+
+7. THIRD-PARTY COMPONENTS
+   The Software includes third-party open-source components, each licensed under
+   its own terms; those terms govern those components and are not superseded by
+   this license. It also composes third-party agent providers over the Agent
+   Client Protocol and hosted APIs; use of those providers is governed by their
+   own terms.
+
+For licensing inquiries, contact: legal@xenostudio.ai
+
+NOTE TO OPERATOR: confirm the exact legal entity name and notice/contact details
+with counsel before public distribution and code-signing (the code-signing
+publisher name must match the registered entity). No public distribution of this
+product is authorized by this file — see docs/PRODUCT_STATUS.md.

package/dist/agentDiscovery.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Finding the agent CLIs already installed on this machine — ADE §5.2.
+ *
+ * @unwired-by-design ADE §9 step 6 — this is the DECISION half; the probe that
+ * walks `PATH` is node-side and belongs with the composition, and the surface
+ * that renders "found, enable?" does not exist yet. Deliberately built first
+ * and alone: the rules here are about what discovery must NOT do — never mark
+ * something enabled, never execute a binary to identify it — and those are
+ * exactly the rules that get quietly relaxed while wiring a UI. Settling them
+ * against a pure function, with gates, is cheaper than arguing them back later.
+ *
+ * §5.2 ranks this above deeper capabilities, and says why: *"A developer whose
+ * existing agent is not found will never reach any other pillar of this
+ * product."* Someone who already runs Claude Code or Codex should see it
+ * offered, not be asked to configure a path for something sitting on their
+ * `PATH`.
+ *
+ * Pure. It is handed the result of looking, and decides what that means — so
+ * every rule below is testable without a filesystem, and the node-side probe
+ * stays a few lines with no policy in it.
+ *
+ * ## 🔴 Found is OFFERED, never ENABLED
+ *
+ * §5.2's words are "scan `PATH` for known agent CLIs and **offer** to enable
+ * them". The distinction is the whole safety story: enabling an agent means
+ * this product will later SPAWN that binary. Auto-enabling whatever happens to
+ * be on `PATH` would execute third-party programs the user never pointed at us
+ * — and `PATH` is not a trust boundary, it is a convenience. So discovery
+ * produces candidates, and a human turns them on.
+ *
+ * ## 🔴 Presence is the signal — the binary is NOT executed to identify it
+ *
+ * The obvious way to confirm `claude` on `PATH` is Claude Code is to run
+ * `claude --version`. That executes an unknown program to find out whether it
+ * is safe to execute, which is backwards. Worse, `PATH` is attacker-influenced
+ * in exactly the environments this matters in (a project-local `node_modules/
+ * .bin`, a compromised shell profile).
+ *
+ * So detection is presence plus location, and version probing is a SEPARATE
+ * step taken after a human has enabled the agent. That is why `version` is
+ * absent here rather than optional-and-usually-missing.
+ */
+/** An agent CLI this product knows how to drive. */
+export interface KnownAgentCli {
+    /** Stable id — becomes the ACP provider id when enabled. */
+    id: string;
+    displayName: string;
+    /**
+     * Executable names to look for, in preference order.
+     *
+     * A list because the same agent ships under different names per platform and
+     * install method, and picking one arbitrarily is how a real install goes
+     * undetected.
+     */
+    executables: string[];
+}
+/** What looking on disk found. Supplied by the composition. */
+export interface AgentCliProbeResult {
+    executable: string;
+    /** Absolute path, when found. Absent means not present. */
+    path?: string;
+}
+export interface DiscoveredAgentCli {
+    id: string;
+    displayName: string;
+    /** The executable that matched, and where. */
+    executable: string;
+    path: string;
+    /**
+     * 🔴 ALWAYS false from discovery. Present so the shape a surface renders
+     * cannot express "found and already on" — enabling is a human act, and a
+     * field that could arrive true would eventually arrive true by accident.
+     */
+    enabled: false;
+}
+export interface AgentDiscoveryResult {
+    found: DiscoveredAgentCli[];
+    /** Known agents that are NOT installed — reported, not silently omitted, so a
+     *  surface can say "Codex: not found" rather than leaving a user wondering
+     *  whether it was even looked for. */
+    missing: Array<{
+        id: string;
+        displayName: string;
+        searched: string[];
+    }>;
+}
+/**
+ * Decides what a set of probe results means.
+ *
+ * `probes` is every executable that was looked for, whether or not it was
+ * found — a caller that only passed hits could not distinguish "not installed"
+ * from "not searched", and those are different answers.
+ */
+export declare function discoverAgentClis(known: readonly KnownAgentCli[], probes: readonly AgentCliProbeResult[]): AgentDiscoveryResult;
+/** Every executable name that must be probed for a given catalog. */
+export declare function executablesToProbe(known: readonly KnownAgentCli[]): string[];
+//# sourceMappingURL=agentDiscovery.d.ts.map

package/dist/agentDiscovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDiscovery.d.ts","sourceRoot":"","sources":["../src/agentDiscovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,EAAE,KAAK,CAAA;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,kBAAkB,EAAE,CAAA;IAC3B;;0CAEsC;IACtC,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CACxE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,MAAM,EAAE,SAAS,mBAAmB,EAAE,GACrC,oBAAoB,CAmCtB;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAM5E"}

package/dist/agentDiscovery.js

@@ -0,0 +1,93 @@
+/**
+ * Finding the agent CLIs already installed on this machine — ADE §5.2.
+ *
+ * @unwired-by-design ADE §9 step 6 — this is the DECISION half; the probe that
+ * walks `PATH` is node-side and belongs with the composition, and the surface
+ * that renders "found, enable?" does not exist yet. Deliberately built first
+ * and alone: the rules here are about what discovery must NOT do — never mark
+ * something enabled, never execute a binary to identify it — and those are
+ * exactly the rules that get quietly relaxed while wiring a UI. Settling them
+ * against a pure function, with gates, is cheaper than arguing them back later.
+ *
+ * §5.2 ranks this above deeper capabilities, and says why: *"A developer whose
+ * existing agent is not found will never reach any other pillar of this
+ * product."* Someone who already runs Claude Code or Codex should see it
+ * offered, not be asked to configure a path for something sitting on their
+ * `PATH`.
+ *
+ * Pure. It is handed the result of looking, and decides what that means — so
+ * every rule below is testable without a filesystem, and the node-side probe
+ * stays a few lines with no policy in it.
+ *
+ * ## 🔴 Found is OFFERED, never ENABLED
+ *
+ * §5.2's words are "scan `PATH` for known agent CLIs and **offer** to enable
+ * them". The distinction is the whole safety story: enabling an agent means
+ * this product will later SPAWN that binary. Auto-enabling whatever happens to
+ * be on `PATH` would execute third-party programs the user never pointed at us
+ * — and `PATH` is not a trust boundary, it is a convenience. So discovery
+ * produces candidates, and a human turns them on.
+ *
+ * ## 🔴 Presence is the signal — the binary is NOT executed to identify it
+ *
+ * The obvious way to confirm `claude` on `PATH` is Claude Code is to run
+ * `claude --version`. That executes an unknown program to find out whether it
+ * is safe to execute, which is backwards. Worse, `PATH` is attacker-influenced
+ * in exactly the environments this matters in (a project-local `node_modules/
+ * .bin`, a compromised shell profile).
+ *
+ * So detection is presence plus location, and version probing is a SEPARATE
+ * step taken after a human has enabled the agent. That is why `version` is
+ * absent here rather than optional-and-usually-missing.
+ */
+/**
+ * Decides what a set of probe results means.
+ *
+ * `probes` is every executable that was looked for, whether or not it was
+ * found — a caller that only passed hits could not distinguish "not installed"
+ * from "not searched", and those are different answers.
+ */
+export function discoverAgentClis(known, probes) {
+    const byExecutable = new Map();
+    for (const probe of probes) {
+        // First writer wins: probes arrive in the order they were searched, and a
+        // later duplicate is a second hit for the same name, not a better one.
+        if (probe.path && !byExecutable.has(probe.executable)) {
+            byExecutable.set(probe.executable, probe.path);
+        }
+    }
+    const found = [];
+    const missing = [];
+    for (const agent of known) {
+        // Preference order is the DECLARED order, so a machine with two names
+        // installed resolves the same way every time.
+        const hit = agent.executables.find((executable) => byExecutable.has(executable));
+        if (hit) {
+            found.push({
+                id: agent.id,
+                displayName: agent.displayName,
+                executable: hit,
+                path: byExecutable.get(hit),
+                enabled: false,
+            });
+        }
+        else {
+            missing.push({
+                id: agent.id,
+                displayName: agent.displayName,
+                searched: [...agent.executables],
+            });
+        }
+    }
+    return { found, missing };
+}
+/** Every executable name that must be probed for a given catalog. */
+export function executablesToProbe(known) {
+    const seen = new Set();
+    for (const agent of known) {
+        for (const executable of agent.executables)
+            seen.add(executable);
+    }
+    return [...seen];
+}
+//# sourceMappingURL=agentDiscovery.js.map

package/dist/agentDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDiscovery.js","sourceRoot":"","sources":["../src/agentDiscovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AA8CH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA+B,EAC/B,MAAsC;IAEtC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC9C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,0EAA0E;QAC1E,uEAAuE;QACvE,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YACtD,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAChD,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,OAAO,GAAoC,EAAE,CAAA;IAEnD,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,sEAAsE;QACtE,8CAA8C;QAC9C,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;QAChF,IAAI,GAAG,EAAE,CAAC;YACR,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,UAAU,EAAE,GAAG;gBACf,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAE;gBAC5B,OAAO,EAAE,KAAK;aACf,CAAC,CAAA;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;aACjC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AAC3B,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CAAC,KAA+B;IAChE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW;YAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;AAClB,CAAC"}

package/dist/capabilityRouting.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Which agents may run a task — ADE §5.2's capability matcher.
+ *
+ * Reached over the host boundary as `fleet.route` (§5.2's "capability matcher
+ * behind host methods"), which is what makes the refusal OBSERVABLE — a refusal
+ * nothing can ask for is not one anyone can act on.
+ *
+ * Pure and provider-neutral: it takes descriptors and returns a decision. It
+ * starts nothing, so it can be asked speculatively ("could this task run?")
+ * without side effects — which is what a scheduler needs before it commits.
+ *
+ * ## The four rules, each of which a naive matcher gets wrong
+ *
+ * 1. **An ABSENT capability is NOT declared.** `AgentCapabilityMatrix` is a
+ *    `Partial<Record<…>>`, so a missing key is the common case, not an
+ *    exception. Reading absence as "probably fine" is how a task reaches an
+ *    agent that never claimed it could do the work.
+ * 2. **`unsupported` and `blocked` are refusals**, and they are DIFFERENT
+ *    refusals — one says never, the other says not now. Both keep the agent out
+ *    of the eligible set; only the reason differs, and the reason is what the
+ *    user acts on.
+ * 3. **`degraded` is eligible, and must be reported.** Refusing it would make
+ *    the product unusable on any partially-configured agent; hiding it would
+ *    silently give someone a worse run than they asked for. So it routes, and
+ *    it says so.
+ * 4. **An unavailable PROVIDER is ineligible however good its matrix is.** A
+ *    capability declared by an agent that cannot run is a claim about a thing
+ *    that will not happen.
+ */
+import type { AgentHarnessCapability, AgentRuntimeProviderDescriptor } from '@xenosystem/agent-interface-contract';
+/** Why one provider was ruled out, in terms a user can act on. */
+export interface CapabilityRejection {
+    providerId: string;
+    /** The capability that ruled it out. Absent when the PROVIDER is unavailable
+     *  rather than any particular capability being missing. */
+    capability?: AgentHarnessCapability;
+    reason: string;
+}
+export interface CapabilityMatch {
+    providerId: string;
+    /**
+     * Capabilities this provider serves in a `degraded` state.
+     *
+     * Non-empty means the task CAN run here and will run worse. Surfacing it is
+     * the difference between an informed choice and a silent downgrade.
+     */
+    degraded: AgentHarnessCapability[];
+}
+export type CapabilityRoutingDecision = {
+    routable: true;
+    matches: CapabilityMatch[];
+    rejected: CapabilityRejection[];
+}
+/**
+ * 🔴 No agent can do this. `reason` names the specific capability nobody
+ * declared, because "no agent is available" sends someone to check their
+ * network while the real answer is that no installed agent does this at all.
+ */
+ | {
+    routable: false;
+    reason: string;
+    rejected: CapabilityRejection[];
+};
+/**
+ * Decides which providers may run a task requiring `required`.
+ *
+ * A task requiring NOTHING is routable to every runnable provider — an empty
+ * requirement list is not a trick question, and refusing it would make the
+ * matcher unusable as a general router.
+ */
+export declare function routeByCapability(providers: readonly AgentRuntimeProviderDescriptor[], required: readonly AgentHarnessCapability[]): CapabilityRoutingDecision;
+//# sourceMappingURL=capabilityRouting.d.ts.map

package/dist/capabilityRouting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityRouting.d.ts","sourceRoot":"","sources":["../src/capabilityRouting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAGV,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,sCAAsC,CAAA;AAE7C,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB;+DAC2D;IAC3D,UAAU,CAAC,EAAE,sBAAsB,CAAA;IACnC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,sBAAsB,EAAE,CAAA;CACnC;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE;AACjF;;;;GAIG;GACD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAA;AAyBxE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,8BAA8B,EAAE,EACpD,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAC1C,yBAAyB,CA+C3B"}

package/dist/capabilityRouting.js

@@ -0,0 +1,124 @@
+/**
+ * Which agents may run a task — ADE §5.2's capability matcher.
+ *
+ * Reached over the host boundary as `fleet.route` (§5.2's "capability matcher
+ * behind host methods"), which is what makes the refusal OBSERVABLE — a refusal
+ * nothing can ask for is not one anyone can act on.
+ *
+ * Pure and provider-neutral: it takes descriptors and returns a decision. It
+ * starts nothing, so it can be asked speculatively ("could this task run?")
+ * without side effects — which is what a scheduler needs before it commits.
+ *
+ * ## The four rules, each of which a naive matcher gets wrong
+ *
+ * 1. **An ABSENT capability is NOT declared.** `AgentCapabilityMatrix` is a
+ *    `Partial<Record<…>>`, so a missing key is the common case, not an
+ *    exception. Reading absence as "probably fine" is how a task reaches an
+ *    agent that never claimed it could do the work.
+ * 2. **`unsupported` and `blocked` are refusals**, and they are DIFFERENT
+ *    refusals — one says never, the other says not now. Both keep the agent out
+ *    of the eligible set; only the reason differs, and the reason is what the
+ *    user acts on.
+ * 3. **`degraded` is eligible, and must be reported.** Refusing it would make
+ *    the product unusable on any partially-configured agent; hiding it would
+ *    silently give someone a worse run than they asked for. So it routes, and
+ *    it says so.
+ * 4. **An unavailable PROVIDER is ineligible however good its matrix is.** A
+ *    capability declared by an agent that cannot run is a claim about a thing
+ *    that will not happen.
+ */
+/** Provider availabilities that can run a turn. `degraded` can; the rest cannot. */
+const RUNNABLE = new Set(['available', 'degraded']);
+/** Capability statuses that permit routing. */
+const PERMITTED = new Set([
+    'available',
+    'degraded',
+]);
+function refusalFor(status, capability, reason) {
+    // `unsupported` and `blocked` are different facts and the wording keeps them
+    // apart: one is a property of the agent, the other of its current state.
+    const base = status === 'unsupported'
+        ? `does not support ${capability}`
+        : `has ${capability} blocked`;
+    return reason ? `${base} — ${reason}` : base;
+}
+/**
+ * Decides which providers may run a task requiring `required`.
+ *
+ * A task requiring NOTHING is routable to every runnable provider — an empty
+ * requirement list is not a trick question, and refusing it would make the
+ * matcher unusable as a general router.
+ */
+export function routeByCapability(providers, required) {
+    const matches = [];
+    const rejected = [];
+    for (const provider of providers) {
+        if (!RUNNABLE.has(provider.availability)) {
+            rejected.push({
+                providerId: provider.id,
+                reason: provider.safeUnavailableReason
+                    ? `is ${provider.availability} — ${provider.safeUnavailableReason}`
+                    : `is ${provider.availability}`,
+            });
+            continue;
+        }
+        const degraded = [];
+        let rejection;
+        for (const capability of required) {
+            const descriptor = provider.capabilities[capability];
+            if (!descriptor) {
+                // Rule 1. Absence is the common case, and it means NOT DECLARED.
+                rejection = {
+                    providerId: provider.id,
+                    capability,
+                    reason: `does not declare ${capability}`,
+                };
+                break;
+            }
+            if (!PERMITTED.has(descriptor.status)) {
+                rejection = {
+                    providerId: provider.id,
+                    capability,
+                    reason: refusalFor(descriptor.status, capability, descriptor.reason),
+                };
+                break;
+            }
+            if (descriptor.status === 'degraded')
+                degraded.push(capability);
+        }
+        if (rejection)
+            rejected.push(rejection);
+        else
+            matches.push({ providerId: provider.id, degraded });
+    }
+    if (matches.length > 0)
+        return { routable: true, matches, rejected };
+    return { routable: false, reason: unroutableReason(providers, required, rejected), rejected };
+}
+/**
+ * Why nothing can run this — named, never generic.
+ *
+ * The distinction that matters to a user: is this task impossible with what
+ * they have installed, or did every capable agent happen to be down? Those lead
+ * to completely different next actions, and "no agent available" answers
+ * neither.
+ */
+function unroutableReason(providers, required, rejected) {
+    if (providers.length === 0)
+        return 'No agent runtimes are configured.';
+    // A capability NO provider declares — the strongest, most actionable answer,
+    // and true regardless of whether the providers are up.
+    const undeclared = required.filter((capability) => providers.every((provider) => provider.capabilities[capability] === undefined));
+    if (undeclared.length > 0) {
+        return `No configured agent declares ${undeclared.join(', ')}.`;
+    }
+    // Every provider was ruled out by availability rather than by capability.
+    if (rejected.length > 0 && rejected.every((entry) => entry.capability === undefined)) {
+        return 'Every agent that could run this task is currently unavailable.';
+    }
+    const named = rejected.find((entry) => entry.capability !== undefined);
+    return named
+        ? `No agent can run this task: every candidate ${named.reason}.`
+        : 'No agent can run this task.';
+}
+//# sourceMappingURL=capabilityRouting.js.map

package/dist/capabilityRouting.js.map

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

package/dist/capabilityTier.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Tier resolution — ADE spec §2.9, "structure comes from the substrate, not from
+ * the agent".
+ *
+ * The apparent cost of running a third-party agent in its own TUI is that it
+ * tells us nothing structured. §2.9's answer is that we should not have been
+ * asking it:
+ *
+ * > "Every run gets a sandbox. Every file write and every process spawn
+ * >  therefore passes through a boundary we own — and **a boundary you own is a
+ * >  sensor.** The sandbox is not only a wall; it is an observation plane. So the
+ * >  question is not *how do we get the agent to narrate its work*. It is *why
+ * >  are we asking the agent at all*."
+ *
+ * ## Two ways to get this wrong, and the spec names both
+ *
+ * **Understating.** §8: "Review, landing, diffs, checkpoints and the command
+ * timeline are tier-1 and therefore work for every agent in every mode,
+ * including a third-party TUI we render nothing of. **Reporting them unavailable
+ * for a third-party agent is a defect, not honest degradation — the data is in
+ * the sandbox.**"
+ *
+ * **Overstating.** §2.9: "The honest boundary: **effects are recoverable, intent
+ * is not.** Review and landing are about effects and therefore work at tier 1
+ * for every agent. Steering and reasoning capture genuinely require tier 3."
+ *
+ * So a resolver that answered "available" for everything would be as wrong as
+ * one that answered "unavailable" without a sandbox — in opposite directions,
+ * and this module is tested against both.
+ *
+ * ## There is no scraping tier
+ *
+ * §2.9: "**Explicitly excluded: parsing the TUI.** Scraping ANSI is the brittle
+ * path that breaks on every vendor UI change. We do not need it, because tier 1
+ * supplies the same facts from a source that cannot change out from under us."
+ *
+ * `CapabilityTier` therefore has no value meaning "scraped". A future
+ * contributor cannot route a capability through ANSI parsing without changing
+ * this type, which is a conversation rather than a commit.
+ */
+/** Where a capability's data comes from. Higher tiers carry more meaning. */
+export type CapabilityTier = 1 | 2 | 3;
+/**
+ * What a capability fundamentally needs.
+ *
+ * The distinction is §2.9's "honest boundary", not an implementation detail:
+ * effects leave traces in the substrate, intent exists only in the agent.
+ */
+export type CapabilityNeed = 'effects' | 'intent';
+/** What this run can actually observe. */
+export interface CapabilitySources {
+    /** Tier 1 — the sandbox filesystem and process tree. */
+    sandboxObservation: boolean;
+    /** Tier 2 — a vendor-supported side channel: hooks, JSONL traces, telemetry.
+     *  NOT scraping; §2.9 excludes that outright. */
+    vendorSideChannel: boolean;
+    /** Tier 3 — the agent speaks ACP. */
+    acp: boolean;
+}
+export type CapabilityResolution = {
+    available: true;
+    tier: CapabilityTier;
+    reason: string;
+} | {
+    available: false;
+    reason: string;
+};
+/**
+ * The §2.9 capability map, stated once.
+ *
+ * Kept as data rather than scattered through call sites so "is this effects or
+ * intent?" has one answer. Getting it wrong for a single capability is how a
+ * surface ends up telling a user that review is unavailable for the agent they
+ * chose — the defect §8 names.
+ */
+export declare const CAPABILITY_NEEDS: {
+    readonly 'file.changes': "effects";
+    readonly 'review.diff': "effects";
+    readonly 'review.hunks': "effects";
+    readonly checkpoints: "effects";
+    readonly 'command.timeline': "effects";
+    readonly landing: "effects";
+    readonly 'steering.mid-turn': "intent";
+    readonly 'reasoning.capture': "intent";
+    readonly 'permission.events': "intent";
+    readonly 'tool.semantics': "intent";
+};
+export type KnownCapability = keyof typeof CAPABILITY_NEEDS;
+/**
+ * Resolves a capability to the highest tier that can actually deliver it.
+ *
+ * `available: false` is reserved for cases where NOTHING can deliver it — never
+ * used as a shorthand for "the agent did not tell us", which is the failure §8
+ * calls a defect.
+ */
+export declare function resolveCapabilityTier(capability: KnownCapability, sources: CapabilitySources): CapabilityResolution;
+/**
+ * True when a capability would be wrongly reported unavailable.
+ *
+ * §8 calls that a DEFECT rather than honest degradation, so it is worth being
+ * able to assert directly — a surface can check itself instead of a human
+ * noticing that review vanished for one agent.
+ */
+export declare function isUnderstatedCapability(capability: KnownCapability, sources: CapabilitySources, reportedAvailable: boolean): boolean;
+//# sourceMappingURL=capabilityTier.d.ts.map

package/dist/capabilityTier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityTier.d.ts","sourceRoot":"","sources":["../src/capabilityTier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEjD,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,kBAAkB,EAAE,OAAO,CAAA;IAC3B;qDACiD;IACjD,iBAAiB,EAAE,OAAO,CAAA;IAC1B,qCAAqC;IACrC,GAAG,EAAE,OAAO,CAAA;CACb;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAesB,CAAA;AAEnD,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAA;AAE3D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,iBAAiB,GACzB,oBAAoB,CAyCtB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,iBAAiB,EAC1B,iBAAiB,EAAE,OAAO,GACzB,OAAO,CAET"}