@multiagency/sdk 0.3.1

package/dist/contract/owner-capabilities.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Owner-app capabilities (P2 manifest v1): what an owner frontend may declare in `contract.json`.
+ * A capability names existing routes so the gateway can refuse a release this platform cannot serve.
+ * It grants nothing: every call is still authorized per session, agent and procedure.
+ */
+export declare const ownerCapabilities: {
+    readonly "gateway-session-v1": {
+        readonly routes: readonly ["/gw/challenge", "/gw/session", "/gw/logout", "/gw/me", "/gw/agents", "/a/<agent>/access"];
+        readonly procedures: readonly [];
+    };
+    readonly "agent-observe-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["setup", "instance", "overview", "policyHistory", "activity", "unresolved", "held", "autopilot/get", "inbox/list", "inbox/dismiss"];
+    };
+    /** A safety control: stopping a running schedule stays reachable on every host that can run one. */
+    readonly "agent-schedule-stop-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["autopilot/stop"];
+    };
+    readonly "agent-funding-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["deposit"];
+    };
+    /** The owning DAO link, funding from it, shielding and sweep: any agent, not only Treasury strategy. */
+    readonly "owner-treasury-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["treasury/get", "treasury/link", "treasury/unlink", "treasury/setConfidential", "treasury/fund", "sweep"];
+    };
+    readonly "owner-intents-v1": {
+        readonly routes: readonly ["/gw/proposals", "/gw/interventions"];
+        readonly procedures: readonly ["owner/prepare", "owner/submit", "owner/status", "owner/pending", "owner/actions"];
+    };
+    readonly "treasury-observe-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["strategy/get", "autopilot/evidence", "autopilot/log", "ledger", "ledgerCsv", "reconcileBooks"];
+    };
+    readonly "treasury-strategy-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["strategy/save", "autopilot/set", "autopilot/enable", "autopilot/tick"];
+    };
+    readonly "treasury-plans-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["rebalance", "externalPlan", "executePlan", "steward/propose"];
+    };
+    readonly "treasury-recovery-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["recover"];
+    };
+    readonly "payables-payments-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["pay", "paymentHistory", "paymentStatus", "invoices", "cancelPreparedInvoice", "ledger", "ledgerCsv", "reconcileBooks"];
+    };
+    readonly "payables-payout-requests-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["payouts/request", "payouts/status"];
+    };
+    readonly "payables-agreements-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["agreements/list", "agreements/propose", "agreements/offer", "agreements/decline"];
+    };
+    readonly "payables-work-orders-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["workOrders/list", "workOrders/get", "workOrders/status", "workOrders/create", "workOrders/prepare", "workOrders/submit", "workOrders/deposit", "workOrders/file"];
+    };
+    readonly "payables-compensation-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["compensation/list", "compensation/agreement", "compensation/review", "compensation/prepare", "compensation/send"];
+    };
+    readonly "payables-recovery-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["recover"];
+    };
+    /** Temporary: guide inference stays in the platform until its extraction (recorded migration gap). */
+    readonly "payables-guide-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["demoGuide/compose"];
+    };
+};
+export type OwnerCapability = keyof typeof ownerCapabilities;
+/** What a host provides, from the areas of the agents assigned to it. `showcase`-only hosts get the neutral set. */
+export declare function providedCapabilities(areas: readonly ("treasury" | "payables")[]): OwnerCapability[];

package/dist/contract/owner-capabilities.js

@@ -0,0 +1,33 @@
+/**
+ * Owner-app capabilities (P2 manifest v1): what an owner frontend may declare in `contract.json`.
+ * A capability names existing routes so the gateway can refuse a release this platform cannot serve.
+ * It grants nothing: every call is still authorized per session, agent and procedure.
+ */
+export const ownerCapabilities = {
+    "gateway-session-v1": { routes: ["/gw/challenge", "/gw/session", "/gw/logout", "/gw/me", "/gw/agents", "/a/<agent>/access"], procedures: [] },
+    "agent-observe-v1": { routes: [], procedures: ["setup", "instance", "overview", "policyHistory", "activity", "unresolved", "held", "autopilot/get", "inbox/list", "inbox/dismiss"] },
+    /** A safety control: stopping a running schedule stays reachable on every host that can run one. */
+    "agent-schedule-stop-v1": { routes: [], procedures: ["autopilot/stop"] },
+    "agent-funding-v1": { routes: [], procedures: ["deposit"] },
+    /** The owning DAO link, funding from it, shielding and sweep: any agent, not only Treasury strategy. */
+    "owner-treasury-v1": { routes: [], procedures: ["treasury/get", "treasury/link", "treasury/unlink", "treasury/setConfidential", "treasury/fund", "sweep"] },
+    "owner-intents-v1": { routes: ["/gw/proposals", "/gw/interventions"], procedures: ["owner/prepare", "owner/submit", "owner/status", "owner/pending", "owner/actions"] },
+    "treasury-observe-v1": { routes: [], procedures: ["strategy/get", "autopilot/evidence", "autopilot/log", "ledger", "ledgerCsv", "reconcileBooks"] },
+    "treasury-strategy-v1": { routes: [], procedures: ["strategy/save", "autopilot/set", "autopilot/enable", "autopilot/tick"] },
+    "treasury-plans-v1": { routes: [], procedures: ["rebalance", "externalPlan", "executePlan", "steward/propose"] },
+    "treasury-recovery-v1": { routes: [], procedures: ["recover"] },
+    "payables-payments-v1": { routes: [], procedures: ["pay", "paymentHistory", "paymentStatus", "invoices", "cancelPreparedInvoice", "ledger", "ledgerCsv", "reconcileBooks"] },
+    "payables-payout-requests-v1": { routes: [], procedures: ["payouts/request", "payouts/status"] },
+    "payables-agreements-v1": { routes: [], procedures: ["agreements/list", "agreements/propose", "agreements/offer", "agreements/decline"] },
+    "payables-work-orders-v1": { routes: [], procedures: ["workOrders/list", "workOrders/get", "workOrders/status", "workOrders/create", "workOrders/prepare", "workOrders/submit", "workOrders/deposit", "workOrders/file"] },
+    "payables-compensation-v1": { routes: [], procedures: ["compensation/list", "compensation/agreement", "compensation/review", "compensation/prepare", "compensation/send"] },
+    "payables-recovery-v1": { routes: [], procedures: ["recover"] },
+    /** Temporary: guide inference stays in the platform until its extraction (recorded migration gap). */
+    "payables-guide-v1": { routes: [], procedures: ["demoGuide/compose"] },
+};
+const neutral = ["gateway-session-v1", "agent-observe-v1", "agent-schedule-stop-v1", "agent-funding-v1", "owner-treasury-v1", "owner-intents-v1"];
+/** What a host provides, from the areas of the agents assigned to it. `showcase`-only hosts get the neutral set. */
+export function providedCapabilities(areas) {
+    const names = Object.keys(ownerCapabilities);
+    return [...neutral, ...names.filter(name => areas.some(area => name.startsWith(`${area}-`)))];
+}

package/dist/contract/owner-client.d.ts

@@ -0,0 +1,99 @@
+import type { z } from "zod";
+import { ownerOutputs, ownerStreams } from "./owner-outputs.js";
+import type { OwnerInputs } from "./owner-inputs.js";
+import { type GatewayDenialScope } from "./gateway.js";
+export type OwnerProcedure = keyof typeof ownerOutputs & keyof OwnerInputs;
+type Stream = (typeof ownerStreams)[number];
+export type OwnerOutput<P extends OwnerProcedure> = z.output<(typeof ownerOutputs)[P]>;
+type Identity = Record<string, unknown>;
+/** Supplementary provider facts on a `provider` failure (not retry flags or authorization decisions). */
+export type RefusalDetails = {
+    availableAt?: string;
+    budgetRemainingUsd?: string;
+};
+/** Per-call options: an aborted read is `unavailable`; an aborted mutation or stream is `unknown` (it may have been accepted). */
+export type OwnerCallOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * Recovery is decided by `kind`, never by message text.
+ * - `session` (401) / `forbidden` (403): from the status alone, with the `source` that refused. A gateway denial adds the `scope` it declares (no
+ *   session, no access to this agent, or no permission for this procedure); without one, the caller picks its default.
+ * - `unresolved` / `busy`: refused before anything was sent; follow existing operations, then try again.
+ * - `refused`: the platform refused before sending (with `code` when it names a reason).
+ * - `provider`: the provider refused or failed; check the recorded outcome before retrying.
+ * - `unavailable`: a read failed or returned an invalid answer; reading again is safe.
+ * - `unknown`: a mutation or stream may have taken effect. Keep `identity`, read the existing records, never resend.
+ * `refused` keeps the HTTP `status` and oRPC `rpcCode` of the encoded refusal. A plain answer that isn't an encoded
+ * oRPC error (a proxy page, or a 404 for a procedure this host lacks) adds its `httpStatus` to `unavailable` or
+ * `unknown`, for diagnosis only: nothing in it proves the handler didn't run, so it never becomes `refused`.
+ */
+export type OwnerFailure = {
+    ok: false;
+    kind: "session";
+    status: 401;
+    error: string;
+    source?: DenialSource;
+    scope?: GatewayDenialScope;
+} | {
+    ok: false;
+    kind: "forbidden";
+    status: 403;
+    error: string;
+    source?: DenialSource;
+    scope?: GatewayDenialScope;
+} | {
+    ok: false;
+    kind: "unresolved" | "busy";
+    error: string;
+} | {
+    ok: false;
+    kind: "refused";
+    error: string;
+    code?: string;
+    status?: number;
+    rpcCode?: string;
+} | {
+    ok: false;
+    kind: "provider";
+    error: string;
+    code?: string;
+    details: RefusalDetails;
+} | {
+    ok: false;
+    kind: "unavailable";
+    httpStatus?: number;
+} | {
+    ok: false;
+    kind: "unknown";
+    procedure: OwnerProcedure;
+    identity: Identity;
+    httpStatus?: number;
+};
+/** Who refused: the gateway (a plain answer, before forwarding) or the agent server (an encoded oRPC error). */
+export type DenialSource = "gateway" | "agent";
+export type OwnerResult<T> = {
+    ok: true;
+    value: T;
+} | OwnerFailure;
+type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Where owner procedures live: `""` or `/a/<agent>` on the page's own host (the gateway session cookie goes same-origin),
+ * or an absolute URL for a caller outside a browser, such as Treasury's scoped machine route
+ * `https://<host>/machine/v1/a/<agent>`. The client adds no credential: a non-browser caller's `fetch` adds the one its
+ * route accepts. A Treasury machine credential is accepted only on that machine route, never on `/a/<agent>/rpc`, and
+ * there is no Payables or DAO machine delegation.
+ */
+export type OwnerBase = "" | `/${string}` | `https://${string}` | `http://${string}`;
+/** Typed owner procedures under an agent base (see OwnerBase), same wire as the app's oRPC client. Never retries. */
+export declare function ownerClient({ base, fetch: send }?: {
+    base?: OwnerBase;
+    fetch?: Fetch;
+}): {
+    /** One read or non-stream mutation; the answer is validated against the published output schema. */
+    call<P extends Exclude<OwnerProcedure, Stream>>(path: P, ...[input, options]: undefined extends OwnerInputs[P] ? [input?: OwnerInputs[P], options?: OwnerCallOptions] : [input: OwnerInputs[P], options?: OwnerCallOptions]): Promise<OwnerResult<OwnerOutput<P>>>;
+    /** A stream's events, each validated; a lost stream or invalid event ends it as `unknown` with the input identity. */
+    stream<P extends Stream>(path: P, input: OwnerInputs[P], options?: OwnerCallOptions): AsyncGenerator<OwnerOutput<P>, OwnerFailure | undefined>;
+};
+export type OwnerClient = ReturnType<typeof ownerClient>;
+export {};

package/dist/contract/owner-client.js

@@ -0,0 +1,146 @@
+import { createORPCClient, ORPCError, RPCLink } from "./orpc-client.js";
+import { ownerOutputs } from "./owner-outputs.js";
+import { gatewayDenialScope } from "./gateway.js";
+import { READS } from "./permissions.js";
+/** oRPC codes that mean the server refused before acting. TIMEOUT and CLIENT_CLOSED_REQUEST are not: the outcome is unknown. */
+const REFUSALS = new Set(["BAD_REQUEST", "NOT_FOUND", "METHOD_NOT_SUPPORTED", "NOT_ACCEPTABLE", "CONFLICT", "PRECONDITION_FAILED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_CONTENT", "TOO_MANY_REQUESTS"]);
+/**
+ * An encoded oRPC error from any copy of `@orpc/client`. A bundler can load the link's copy apart from this module's
+ * (Module Federation shares `@orpc/client` but not `@orpc/client/fetch`; seen in the dashboard's built API), and
+ * `instanceof ORPCError` then fails across them, turning a proven refusal into `unknown`. Every version names its error
+ * `ORPCError` and carries a string `code`.
+ */
+const isRpcError = (error) => error instanceof ORPCError || (error instanceof Error && error.name === "ORPCError" && typeof error.code === "string");
+/** A non-2xx answer that isn't an encoded oRPC error. */
+class PlainAnswer extends Error {
+    status;
+    constructor(status) {
+        super(`HTTP ${status}`);
+        this.status = status;
+    }
+}
+class GatewayDenial extends Error {
+    status;
+    scope;
+    constructor(status, message, scope) {
+        super(message);
+        this.status = status;
+        this.scope = scope;
+    }
+}
+/** Typed owner procedures under an agent base (see OwnerBase), same wire as the app's oRPC client. Never retries. */
+export function ownerClient({ base = "", fetch: send = globalThis.fetch } = {}) {
+    /** One call's client: it records that call's HTTP status, which oRPC's errors don't carry. */
+    const procedure = (path, answered) => {
+        // oRPC's URL type omits `http://`; the link only concatenates it and hands it to `fetch` below.
+        const client = createORPCClient(new RPCLink({ url: `${base}/rpc`, fetch: (url, init) => answer(url, init, answered) }));
+        return path.split("/").reduce((node, key) => node[key], client);
+    };
+    async function answer(url, init, answered) {
+        // Same origin in a browser; outside one, relative paths resolve against localhost (tests and tools pass their own fetch).
+        const response = await send(new URL(url, globalThis.location?.href ?? "http://localhost"), init);
+        answered(response.status);
+        if (response.ok)
+            return response;
+        // Gateway denials are plain JSON, not encoded RPC errors; the status alone decides. Any other plain answer keeps
+        // only its status: it is classified as lost below.
+        const body = await response.clone().json().catch(() => null);
+        if (typeof body?.json?.code === "string")
+            return response;
+        if (response.status === 401 || response.status === 403)
+            throw new GatewayDenial(response.status, typeof body?.error === "string" ? body.error : response.status === 401 ? "Sign in again." : "This account may not do that.", gatewayDenialScope(body));
+        throw new PlainAnswer(response.status);
+    }
+    function failure(error, path, identity, status) {
+        const mutation = !READS.has(path);
+        const lost = mutation ? { ok: false, kind: "unknown", procedure: path, identity } : { ok: false, kind: "unavailable" };
+        if (error instanceof GatewayDenial) {
+            const scope = error.scope && { scope: error.scope };
+            return error.status === 401 ? { ok: false, kind: "session", status: 401, error: error.message, source: "gateway", ...scope }
+                : { ok: false, kind: "forbidden", status: 403, error: error.message, source: "gateway", ...scope };
+        }
+        if (error instanceof PlainAnswer)
+            return error.status > 0 ? { ...lost, httpStatus: error.status } : lost;
+        if (!isRpcError(error))
+            return lost;
+        if (error.code === "UNAUTHORIZED")
+            return { ok: false, kind: "session", status: 401, error: error.message, source: "agent" };
+        if (error.code === "FORBIDDEN")
+            return { ok: false, kind: "forbidden", status: 403, error: error.message, source: "agent" };
+        const data = (error.data ?? {});
+        const code = typeof data.code === "string" ? data.code : undefined;
+        if (data.kind === "unresolved" || data.kind === "busy")
+            return { ok: false, kind: data.kind, error: error.message };
+        const refusal = { ...(status !== undefined && { status }), rpcCode: error.code };
+        if (data.kind === "refused")
+            return { ok: false, kind: "refused", error: error.message, ...(code && { code }), ...refusal };
+        if (data.kind === "provider")
+            return { ok: false, kind: "provider", error: error.message, ...(code && { code }), details: {
+                    ...(typeof data.availableAt === "string" && { availableAt: data.availableAt }),
+                    ...(typeof data.budgetRemainingUsd === "string" && { budgetRemainingUsd: data.budgetRemainingUsd })
+                } };
+        // Untyped refusal codes come before the handler acted (input validation, not found); anything else may follow an effect.
+        return REFUSALS.has(error.code) ? { ok: false, kind: "refused", error: error.message, ...(code && { code }), ...refusal } : lost;
+    }
+    return {
+        /** One read or non-stream mutation; the answer is validated against the published output schema. */
+        async call(path, ...[input, options]) {
+            const identity = (input ?? {});
+            let output;
+            let status;
+            try {
+                output = await procedure(path, answered => { status = answered; })(input, { signal: options?.signal });
+            }
+            catch (error) {
+                return failure(error, path, identity, status);
+            }
+            const parsed = ownerOutputs[path].safeParse(output);
+            if (parsed.success)
+                return { ok: true, value: parsed.data };
+            return READS.has(path) ? { ok: false, kind: "unavailable" } : { ok: false, kind: "unknown", procedure: path, identity };
+        },
+        /** A stream's events, each validated; a lost stream or invalid event ends it as `unknown` with the input identity. */
+        async *stream(path, input, options) {
+            const identity = (input ?? {});
+            let events;
+            let status;
+            try {
+                events = await procedure(path, answered => { status = answered; })(input, { signal: options?.signal });
+            }
+            catch (error) {
+                return failure(error, path, identity, status);
+            }
+            let started = false;
+            const iterator = events[Symbol.asyncIterator]();
+            // An open stream must end on abort even if the transport keeps it open: race each read with the signal.
+            const aborted = new Promise(resolve => {
+                if (options?.signal?.aborted)
+                    resolve("aborted");
+                options?.signal?.addEventListener("abort", () => resolve("aborted"), { once: true });
+            });
+            try {
+                for (;;) {
+                    const next = await Promise.race([iterator.next(), aborted]);
+                    if (next === "aborted") {
+                        void iterator.return?.();
+                        return { ok: false, kind: "unknown", procedure: path, identity };
+                    }
+                    if (next.done)
+                        break;
+                    started = true;
+                    const parsed = ownerOutputs[path].safeParse(next.value);
+                    if (!parsed.success) {
+                        void iterator.return?.();
+                        return { ok: false, kind: "unknown", procedure: path, identity };
+                    }
+                    yield parsed.data;
+                }
+            }
+            catch (error) {
+                // After any event, part of the stream may have taken effect: only a failure before the first event keeps its kind.
+                return started ? { ok: false, kind: "unknown", procedure: path, identity } : failure(error, path, identity, status);
+            }
+            return undefined;
+        },
+    };
+}