pilotswarm-sdk 0.5.29 → 0.5.31

package/api/index.d.ts

@@ -84,3 +84,43 @@ export declare class HttpApiTransport {
     stop(): Promise<void>;
     [method: string]: any;
 }
+
+// ── Session-tree access predicate (src/session-authz.js) ──────────
+// Pure; shared by the portal runtime and the worker's agent tools so the
+// "may this principal touch this session?" answer has ONE implementation.
+
+export interface SessionAccessSnapshot {
+    rootSessionId: string;
+    isSystem: boolean;
+    visibility: "private" | "shared_read" | "shared_write";
+    owner: { displayName?: string | null; email?: string | null; subject?: string | null } | null;
+    viewerIsOwner: boolean;
+    viewerShareAccess: "read" | "write" | null;
+}
+
+export interface SessionAccessDecision {
+    allowed: boolean;
+    /** Report NOT_FOUND rather than FORBIDDEN: an admitted caller must not be able to probe which session ids exist. */
+    notFound?: boolean;
+    reason?: string;
+    /** An admin reached something a plain user in the same position could not see. Audit it. */
+    breakGlass?: boolean;
+}
+
+export type SessionAccessClass =
+    | "session:read" | "session:write" | "session:manage" | "session:destroy" | "session:share";
+
+export declare const SESSION_VISIBILITY_VALUES: readonly string[];
+export declare function normalizeVisibility(value: unknown, fallback: string): string;
+export declare function systemSessionsReadable(env?: Record<string, string | undefined>): boolean;
+export declare function relationFor(snapshot: SessionAccessSnapshot | null, opts?: { isAdmin?: boolean }): "owner" | "admin" | "collaborator";
+export declare function evaluateSessionAccess(
+    accessClass: SessionAccessClass,
+    snapshot: SessionAccessSnapshot | null,
+    opts?: { isAdmin?: boolean; systemReadable?: boolean },
+): SessionAccessDecision;
+/** Archive reads are owner-or-admin ONLY — never a share. See proposal §15 A3. */
+export declare function evaluateArchiveAccess(
+    snapshot: SessionAccessSnapshot | null,
+    opts?: { isAdmin?: boolean },
+): SessionAccessDecision;

package/api/index.js

@@ -12,5 +12,13 @@ export {
     artifactDownloadPath,
     ApiError,
 } from "./src/protocol.js";
+export {
+    SESSION_VISIBILITY_VALUES,
+    normalizeVisibility,
+    systemSessionsReadable,
+    relationFor,
+    evaluateSessionAccess,
+    evaluateArchiveAccess,
+} from "./src/session-authz.js";
 export { ApiClient } from "./src/api-client.js";
 export { HttpApiTransport } from "./src/http-api-transport.js";

package/api/src/api-client.js

@@ -68,7 +68,16 @@ export class ApiClient {
     // ── HTTP ────────────────────────────────────────────────────────────
 
     async authHeaders(extra = {}) {
-        const token = await this.getAccessToken();
+        // Bounded: a token getter that neither resolves nor rejects (wedged
+        // silent renewal) must not hang every REST call behind it — proceed
+        // tokenless after 12s and let the server's 401 drive re-auth.
+        const token = await Promise.race([
+            Promise.resolve().then(() => this.getAccessToken()).catch(() => null),
+            new Promise((resolve) => {
+                const t = setTimeout(() => resolve(null), 12_000);
+                if (typeof t?.unref === "function") t.unref();
+            }),
+        ]);
         const headers = { ...extra };
         if (token) headers.authorization = `Bearer ${token}`;
         return headers;

package/api/src/http-api-transport.js

@@ -64,8 +64,28 @@ export class HttpApiTransport {
     }
 
     async listCreatableAgents() {
-        return this.bootstrap?.creatableAgents || this.api.call("listCreatableAgents");
-    }
+        // Always fetch: the server unions baked agents with viewer-scoped
+        // registry packages, so the bootstrap snapshot (baked-only, captured
+        // at page load) would hide packages and go stale across publishes.
+        try {
+            return await this.api.call("listCreatableAgents");
+        } catch {
+            return this.bootstrap?.creatableAgents || [];
+        }
+    }
+
+    // ── Agent packages (docs/proposals/agent-packages.md) ────────
+    listAgentPackages() { return this.api.call("listAgentPackages"); }
+    getAgentPackage(name) { return this.api.call("getAgentPackage", { name }); }
+    getAgentPackageTree(name, semver) { return this.api.call("getAgentPackageTree", { name, ...(semver ? { semver } : {}) }); }
+    getAgentPackageFile(name, semver, filePath) { return this.api.call("getAgentPackageFile", { name, filePath, ...(semver ? { semver } : {}) }); }
+    uploadAgentPackage(files, scope) { return this.api.call("uploadAgentPackage", { files, scope }); }
+    listAgentWorkerState() { return this.api.call("listAgentWorkerState"); }
+    listWorkers() { return this.api.call("listWorkers"); }
+    setAgentPackageScope(name, scope) { return this.api.call("setAgentPackageScope", { name, scope }); }
+    setAgentPackageEnabled(name, enabled) { return this.api.call("setAgentPackageEnabled", { name, enabled }); }
+    pinAgentPackageVersion(name, semver) { return this.api.call("pinAgentPackageVersion", { name, semver }); }
+    deleteAgentPackage(name) { return this.api.call("deleteAgentPackage", { name }); }
 
     getSessionCreationPolicy() {
         return this.bootstrap?.sessionCreationPolicy || null;

package/api/src/protocol.js

@@ -86,6 +86,16 @@ export const OPERATIONS = [
     { name: "downloadArtifact", access: "session:read", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/text", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact content as text (JSON envelope). Binary: GET …/download." },
     { name: "uploadArtifact", access: "session:write", method: "PUT", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename"), content: body(), contentType: body(), contentEncoding: body() }, summary: "Upload artifact content (base64 for binary; 2 MB JSON limit)." },
     { name: "deleteArtifact", access: "session:manage", method: "DELETE", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Delete an artifact." },
+    // These three were dispatchable (runtime.js) and access-classified
+    // (authz.js RPC_ONLY_ACCESS) but reachable only through the legacy
+    // /api/rpc path — every ApiClient.call() of them threw "Unknown API
+    // operation" client-side, which silently broke the MCP artifact
+    // read-base64/copy/pin actions in web mode. Table rows give them
+    // generated routes with the same authz (session:copy gates
+    // fromSessionId for read + toSessionId for write by param name).
+    { name: "readArtifactBase64", access: "session:read", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/base64", params: { sessionId: path("sessionId"), filename: path("filename"), maxBytes: query("number") }, summary: "Artifact content as base64 (JSON envelope; maxBytes caps the read, truncated flag set when hit)." },
+    { name: "copyArtifact", access: "session:copy", method: "POST", path: "/artifacts/copy", params: { fromSessionId: body(), fromFilename: body(), toSessionId: body(), toFilename: body() }, summary: "Copy an artifact across sessions (read access on the source, write on the target)." },
+    { name: "setArtifactPinned", access: "session:manage", method: "PUT", path: "/sessions/:sessionId/artifacts/:filename/pinned", params: { sessionId: path("sessionId"), filename: path("filename"), pinned: body() }, summary: "Pin/unpin an artifact (pinned artifacts survive retention sweeps)." },
 
     // ── Management: sessions ────────────────────────────────────────────
     { name: "listSessionsPage", access: "session:list", method: "GET", path: "/management/sessions", params: { limit: query("number"), cursor: query("json"), includeDeleted: query("boolean") }, summary: "Keyset-paginated session listing." },
@@ -181,6 +191,21 @@ export const OPERATIONS = [
     { name: "listCreatableAgents", access: "authed", method: "GET", path: "/agents", summary: "Agents sessions can be created for." },
     { name: "getSessionCreationPolicy", access: "authed", method: "GET", path: "/session-creation-policy", summary: "Session creation policy." },
 
+    // ── Agent packages (docs/proposals/agent-packages.md) ───────────────
+    // Fixed segments (sources / upload / worker-state) are registered BEFORE
+    // the :name routes — Express matches in table order.
+    { name: "listAgentPackages", access: "authed", method: "GET", path: "/agent-packages", summary: "Agent packages visible to the caller: shared + own user-scope (admins see all)." },
+    { name: "uploadAgentPackage", access: "authed", method: "POST", path: "/agent-packages/upload", params: { files: body(), scope: body() }, summary: "Publish a package from inline files ([{path, contentBase64}], ≤ 2 MB total); validates, canonically packs, and registers as the caller." },
+    { name: "listAgentWorkerState", access: "fleet:admin", method: "GET", path: "/agent-packages/worker-state", admin: true, summary: "Per-worker installed package state (fleet adoption). Hard admin gate: the installed map enumerates every package name, including user-scope ones. [admin]" },
+    { name: "listWorkers", access: "fleet:admin", method: "GET", path: "/workers", admin: true, summary: "Worker registry (0040): every registered worker with pool, lifecycle phase, liveness, write-once info, health snapshot, and per-domain state. Hard admin gate. [admin]" },
+    { name: "getAgentPackage", access: "authed", method: "GET", path: "/agent-packages/:name", params: { name: path("name") }, summary: "One package with its full version history." },
+    { name: "getAgentPackageTree", access: "authed", method: "GET", path: "/agent-packages/:name/tree", params: { name: path("name"), semver: query("string") }, summary: "File tree of the package tarball (workspace viewer). Defaults to the active version." },
+    { name: "getAgentPackageFile", access: "authed", method: "GET", path: "/agent-packages/:name/file", params: { name: path("name"), semver: query("string"), filePath: query("string") }, summary: "One file from the package tarball (preview; text size-capped, binary flagged)." },
+    { name: "setAgentPackageScope", access: "authed", method: "PUT", path: "/agent-packages/:name/scope", params: { name: path("name"), scope: body() }, summary: "Promote (shared) or demote (user). Creator or admin; running agents unaffected." },
+    { name: "setAgentPackageEnabled", access: "authed", method: "PUT", path: "/agent-packages/:name/enabled", params: { name: path("name"), enabled: body() }, summary: "Enable/disable a package fleet-wide. Creator or admin." },
+    { name: "pinAgentPackageVersion", access: "authed", method: "PUT", path: "/agent-packages/:name/active", params: { name: path("name"), semver: body() }, summary: "Pin the active version (rollback). Creator or admin; fleet converges on the next epoch poll." },
+    { name: "deleteAgentPackage", access: "authed", method: "DELETE", path: "/agent-packages/:name", params: { name: path("name") }, summary: "Delete a package: every version and its artifacts. Creator or admin. Live sessions using its agents fail resolution on their next turn." },
+
     // ── Current user profile ────────────────────────────────────────────
     { name: "getCurrentUserProfile", access: "authed", method: "GET", path: "/me/profile", summary: "Profile of the authenticated principal." },
     { name: "setCurrentUserProfileSettings", access: "authed", method: "PATCH", path: "/me/profile/settings", params: { settings: body() }, summary: "Replace profile settings." },

package/api/src/session-authz.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Types for the shared session-tree access predicate.
+ *
+ * The implementation is plain ESM JS (it is imported by the portal, which is
+ * not TypeScript), so the worker needs this to consume it without `any`.
+ * Typing matters more than usual here: `allowed` and `notFound` mean opposite
+ * things to a caller, and an untyped decision object is one typo away from a
+ * gate that always passes.
+ */
+
+export interface SessionAccessSnapshot {
+    rootSessionId?: string;
+    isSystem: boolean;
+    visibility: "private" | "shared_read" | "shared_write";
+    owner: { displayName?: string | null; email?: string | null; subject?: string | null } | null;
+    viewerIsOwner: boolean;
+    viewerShareAccess: "read" | "write" | null;
+}
+
+export interface SessionAccessDecision {
+    allowed: boolean;
+    /** Report NOT_FOUND rather than FORBIDDEN — an admitted caller must not be able to probe which session ids exist. */
+    notFound?: boolean;
+    reason?: string;
+    /** An admin reached something a plain user in the same position could not see. Audit it. */
+    breakGlass?: boolean;
+}
+
+export type SessionAccessClass =
+    | "session:read"
+    | "session:write"
+    | "session:manage"
+    | "session:destroy"
+    | "session:share";
+
+export declare const SESSION_VISIBILITY_VALUES: readonly string[];
+
+export declare function normalizeVisibility(value: unknown, fallback: string): string;
+
+/** Whether ordinary users may READ system sessions (SESSIONS_SYSTEM_VISIBILITY; default true). */
+export declare function systemSessionsReadable(env?: Record<string, string | undefined>): boolean;
+
+export declare function relationFor(
+    snapshot: SessionAccessSnapshot | null,
+    opts?: { isAdmin?: boolean },
+): "owner" | "admin" | "collaborator";
+
+export declare function evaluateSessionAccess(
+    accessClass: SessionAccessClass,
+    snapshot: SessionAccessSnapshot | null,
+    opts?: { isAdmin?: boolean; systemReadable?: boolean },
+): SessionAccessDecision;
+
+/** Archive reads are owner-or-admin ONLY — never a share. See proposal §15 A3. */
+export declare function evaluateArchiveAccess(
+    snapshot: SessionAccessSnapshot | null,
+    opts?: { isAdmin?: boolean },
+): SessionAccessDecision;
+
+/** A sign-in role observation read from the users table. */
+export interface RoleObservation {
+    role?: string | null;
+    seenAt?: Date | null;
+}
+
+/** How old a recorded sign-in role may be and still confer privilege. */
+export declare const ROLE_OBSERVATION_MAX_AGE_MS: number;
+
+/**
+ * Does a recorded sign-in role still make this principal an administrator?
+ * Every unknown resolves to `false`.
+ */
+export declare function evaluateRoleObservation(
+    observation: RoleObservation | null,
+    opts?: { now?: number; maxAgeMs?: number; principal?: { provider?: string; subject?: string } | null },
+): { isAdmin: boolean; reason?: string };

package/api/src/session-authz.js

@@ -0,0 +1,240 @@
+/**
+ * Session-tree access predicate — the ONE implementation, shared by every
+ * surface that has to answer "may this principal touch this session?".
+ *
+ * It lived in `packages/app/web/authz.js` and served the portal alone. The
+ * worker now needs the same answer: agent tools that read sessions must reach
+ * exactly what their session's OWNER could reach, and a second implementation
+ * would be a second thing to get wrong. So the pure half moved here, into the
+ * dependency both sides already have. The portal re-exports it, unchanged.
+ *
+ * Deliberately pure: no I/O, no env, no database. Callers fetch the access
+ * snapshot (`catalog.getSessionAccess`) and pass it in. That is what makes it
+ * usable from an Express route and from inside a tool handler.
+ *
+ * @module
+ */
+
+/**
+ * @typedef {object} SessionAccessSnapshot
+ * @property {string}  rootSessionId
+ * @property {boolean} isSystem
+ * @property {"private"|"shared_read"|"shared_write"} visibility
+ * @property {{displayName?: string|null, email?: string|null, subject?: string|null}|null} owner
+ * @property {boolean} viewerIsOwner
+ * @property {"read"|"write"|null} viewerShareAccess
+ */
+
+export const SESSION_VISIBILITY_VALUES = Object.freeze(["private", "shared_read", "shared_write"]);
+
+const VISIBILITY_SET = new Set(SESSION_VISIBILITY_VALUES);
+
+export function normalizeVisibility(value, fallback) {
+    const normalized = String(value || "").trim().toLowerCase();
+    return VISIBILITY_SET.has(normalized) ? normalized : fallback;
+}
+
+/**
+ * Are system sessions readable by ordinary users on this deployment?
+ *
+ * The portal reads `SESSIONS_SYSTEM_VISIBILITY` for exactly this; the worker
+ * must reach the same answer or the same user would see the PilotSwarm root
+ * in their session list but be told it does not exist by an agent. Default
+ * "read" — hiding them is the opt-in.
+ */
+export function systemSessionsReadable(env = (typeof process !== "undefined" ? process.env : {})) {
+    return String(env?.SESSIONS_SYSTEM_VISIBILITY || "").trim().toLowerCase() !== "admin";
+}
+
+function ownerLabel(snapshot) {
+    return snapshot?.owner?.displayName || snapshot?.owner?.email || snapshot?.owner?.subject || "another user";
+}
+
+/**
+ * The caller's relation to a session tree, recorded on message payloads and
+ * shown to the agent in multi-writer sessions.
+ */
+export function relationFor(snapshot, { isAdmin } = {}) {
+    if (snapshot?.viewerIsOwner) return "owner";
+    if (isAdmin) return "admin";
+    return "collaborator";
+}
+
+/**
+ * Evaluate one session-scoped access class against an access snapshot.
+ *
+ * @param {"session:read"|"session:write"|"session:manage"|"session:destroy"|"session:share"} accessClass
+ * @param {SessionAccessSnapshot|null} snapshot  result of getSessionAccess (null = missing/deleted)
+ * @param {{isAdmin?: boolean, systemReadable?: boolean}} [opts]
+ * @returns {{allowed: boolean, notFound?: boolean, reason?: string, breakGlass?: boolean}}
+ */
+export function evaluateSessionAccess(accessClass, snapshot, { isAdmin = false, systemReadable = true } = {}) {
+    if (!snapshot) {
+        // Missing/deleted session: let the underlying operation produce its
+        // own not-found; nothing to protect.
+        return { allowed: true };
+    }
+
+    if (isAdmin) {
+        // Admins pass everything; flag break-glass when this would have been
+        // invisible to a plain user in the same position.
+        const wouldBeInvisible = !snapshot.viewerIsOwner
+            && !snapshot.isSystem
+            && snapshot.visibility === "private"
+            && !snapshot.viewerShareAccess;
+        return { allowed: true, breakGlass: wouldBeInvisible };
+    }
+
+    const isRead = accessClass === "session:read";
+
+    if (snapshot.isSystem) {
+        // When system sessions are hidden from users, every class 404s so a
+        // write attempt can't confirm the session exists (review LOW-2).
+        if (!systemReadable) return { allowed: false, notFound: true };
+        if (isRead) return { allowed: true };
+        return { allowed: false, reason: "System sessions are managed by administrators." };
+    }
+
+    const canRead = snapshot.viewerIsOwner
+        || snapshot.visibility === "shared_read"
+        || snapshot.visibility === "shared_write"
+        || Boolean(snapshot.viewerShareAccess);
+
+    if (isRead) {
+        return canRead ? { allowed: true } : { allowed: false, notFound: true };
+    }
+
+    // Anything beyond read on an unreadable session is also a 404 — the
+    // caller must not learn the session exists from the error shape.
+    if (!canRead) return { allowed: false, notFound: true };
+
+    if (accessClass === "session:write") {
+        const canWrite = snapshot.viewerIsOwner
+            || snapshot.visibility === "shared_write"
+            || snapshot.viewerShareAccess === "write";
+        return canWrite
+            ? { allowed: true }
+            : { allowed: false, reason: `You have read access to this session; write access is required. Ask ${ownerLabel(snapshot)} for write access.` };
+    }
+
+    // manage / destroy / share: owner only (admin handled above).
+    return snapshot.viewerIsOwner
+        ? { allowed: true }
+        : { allowed: false, reason: `Only the session owner (${ownerLabel(snapshot)}) or an admin can do this.` };
+}
+
+/**
+ * Archive (dehydrated session tar) access — owner or admin ONLY, never a
+ * share. Deliberately NOT `evaluateSessionAccess("session:read", …)`.
+ *
+ * The tar is raw session state: pre-compaction history the UI no longer
+ * displays, full tool-call arguments (which can carry secrets a user pasted),
+ * internal scratch. Sharing a session shares a *view* of a conversation; it
+ * was never an offer of the substrate underneath. See the Agent Manager
+ * proposal, §15 A3.
+ *
+ * @param {SessionAccessSnapshot|null} snapshot
+ * @param {{isAdmin?: boolean}} [opts]
+ * @returns {{allowed: boolean, notFound?: boolean, reason?: string, breakGlass?: boolean}}
+ */
+export function evaluateArchiveAccess(snapshot, { isAdmin = false } = {}) {
+    if (!snapshot) return { allowed: true };
+    if (isAdmin) {
+        // Reading someone else's raw session state is exactly what the
+        // authz_audit table calls a break-glass read.
+        return { allowed: true, breakGlass: !snapshot.viewerIsOwner };
+    }
+    if (snapshot.viewerIsOwner) return { allowed: true };
+    if (snapshot.viewerShareAccess || snapshot.visibility !== "private") {
+        return {
+            allowed: false,
+            reason:
+                "Session archives are available to the session owner and administrators only. "
+                + "A share grants the conversation, not the raw session state behind it.",
+        };
+    }
+    return { allowed: false, notFound: true };
+}
+
+/**
+ * How old a recorded sign-in role may be and still confer privilege.
+ *
+ * The stored role is an OBSERVATION — the last thing the identity provider
+ * told the portal — so it decays. An active portal user re-confirms it every
+ * few minutes; a principal who has not authenticated within this window is
+ * treated as a plain user, which is the fail-closed direction.
+ *
+ * The failure this bounds is concrete: an admin is demoted in the identity
+ * provider and never opens the portal again, while a cron-driven session of
+ * theirs keeps firing turns. Without a ceiling that session keeps fleet reach
+ * forever, because nothing would ever contradict the stored `admin`.
+ */
+export const ROLE_OBSERVATION_MAX_AGE_MS = 12 * 60 * 60 * 1000;
+
+/**
+ * The only principal that may ever hold the `anonymous` role.
+ *
+ * `anonymous` is issued by `authorizePrincipal(null, policy)` — the
+ * auth-disabled branch — and that branch pairs it with
+ * `createNoAuthUnknownPrincipal()`, which is this exact identity. So the
+ * binding below is not a new restriction; it is the existing invariant,
+ * written down where it is relied upon.
+ */
+const ANONYMOUS_PRINCIPAL = { provider: "none", subject: "unknown" };
+
+/**
+ * Does a recorded sign-in role still make this principal an administrator?
+ *
+ * Separate from `evaluateSessionAccess` on purpose: that answers "may this
+ * viewer touch this session", this answers "is this viewer privileged at all".
+ * It is a pure function so the fail-closed paths can be tested without a
+ * database, a worker, or a clock.
+ *
+ * `anonymous` counts as admin, because an auth-disabled deployment is a
+ * trusted one and the portal already grants it full access there. A worker
+ * that disagreed would make agents quietly more restricted than the UI beside
+ * them.
+ *
+ * But `anonymous` is a NAME being trusted to GRANT, which is the one direction
+ * the proposal's own A10 rule says is never safe — a forged name can only put
+ * you inside a denylist, never outside one, and this is the opposite shape. So
+ * it is admitted only for the single principal that can legitimately carry it.
+ * Nothing today can write `anonymous` for a named user; this makes that a
+ * property of the code rather than a property of three other files staying
+ * the way they are.
+ *
+ * Every unknown resolves to `false`: no role, an unrecognized role, a missing
+ * timestamp, or an observation past the ceiling.
+ *
+ * @param {{role?: string|null, seenAt?: Date|null}|null} observation
+ * @param {{now?: number, maxAgeMs?: number, principal?: {provider?: string, subject?: string}|null}} [opts]
+ * @returns {{isAdmin: boolean, reason?: string}}
+ */
+export function evaluateRoleObservation(observation, { now = Date.now(), maxAgeMs = ROLE_OBSERVATION_MAX_AGE_MS, principal = null } = {}) {
+    const role = observation?.role ?? null;
+    if (role !== "admin" && role !== "anonymous") {
+        return { isAdmin: false, reason: role ? `role is '${role}'` : "no role recorded" };
+    }
+    if (role === "anonymous"
+        && !(principal
+            && principal.provider === ANONYMOUS_PRINCIPAL.provider
+            && principal.subject === ANONYMOUS_PRINCIPAL.subject)) {
+        return {
+            isAdmin: false,
+            reason: "the anonymous role belongs to the auth-disabled principal only",
+        };
+    }
+    const seenAt = observation?.seenAt ?? null;
+    if (!(seenAt instanceof Date) || Number.isNaN(seenAt.getTime())) {
+        return { isAdmin: false, reason: "role has no observation timestamp" };
+    }
+    // A future timestamp (clock skew between portal and worker) is not
+    // suspicious enough to refuse, but it must never extend the window
+    // either — which comparing the elapsed age against the ceiling already
+    // guarantees, since a negative age is under it.
+    const age = now - seenAt.getTime();
+    if (age > maxAgeMs) {
+        return { isAdmin: false, reason: `role observation is stale (${Math.floor(age / 3600_000)}h old)` };
+    }
+    return { isAdmin: true };
+}

package/dist/agent-fqn.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Fully-qualified agent/package names.
+ *
+ *   <package>                        bare — own enabled copy, then shared
+ *   __shared:<package>[:<semver>]    the deployment-wide copy, explicitly
+ *   <owner>:<package>[:<semver>]     a named owner's copy
+ *
+ * ── The collision this module exists to manage ──────────────────────────
+ *
+ * `a:b` was ALREADY meaningful before namespaces: the agent resolver reads it
+ * as `namespace:agentName` (a plugin's `plugin.json` name). §9 wants the same
+ * syntax to mean `owner:package`. Both readings are legitimate and neither can
+ * be dropped without breaking something.
+ *
+ * So this parser never guesses. A two-segment name is reported as AMBIGUOUS —
+ * carrying both readings — and the caller resolves in a defined order
+ * (namespace first, preserving today's behaviour, then owner). Only forms that
+ * are structurally unmistakable are classified outright:
+ *
+ *   - a `__`-prefixed first segment is a RESERVED SENTINEL, so `__shared:x`
+ *     can only ever be an FQN;
+ *   - three segments end in a semver, which namespaces never had.
+ *
+ * ── Why `__` is reserved ────────────────────────────────────────────────
+ *
+ * `__shared` has to be unforgeable: if a user could register the subject
+ * `__shared`, or publish a package under it, they would capture every
+ * unqualified reference that meant "the deployment's copy". Reserving the
+ * whole prefix (not just the one token) keeps future sentinels mintable at
+ * zero cost — and per §15 A10, a name may DENY but must never GRANT, which is
+ * exactly how this is used: `__shared` selects a scope, it never confers rights.
+ *
+ * @module
+ */
+/** The reserved sentinel for the deployment-wide namespace. */
+export declare const SHARED_SENTINEL = "__shared";
+/** Any name starting with this is reserved for the platform. */
+export declare const RESERVED_PREFIX = "__";
+export type AgentFqnKind = "bare" | "shared" | "owner" | "ambiguous" | "invalid";
+export interface AgentFqn {
+    kind: AgentFqnKind;
+    /** The package/agent name — always present except for `invalid`. */
+    name: string;
+    /** Owner segment as written, for `owner` (and the owner reading of `ambiguous`). */
+    ownerRef?: string;
+    /** Namespace reading of an ambiguous two-segment name. */
+    namespaceRef?: string;
+    /** Pinned version, when the caller named one. */
+    semver?: string;
+    /** Why the input was rejected. Present only for `invalid`. */
+    reason?: string;
+}
+/**
+ * Is this name reserved for the platform?
+ *
+ * Used at BOTH gates the design names: package publish, and user registration.
+ * Checking only one of them would leave the sentinel forgeable from the other
+ * side.
+ */
+export declare function isReservedName(value: string): boolean;
+export declare function isSemver(value: string): boolean;
+/**
+ * Parse a possibly-qualified agent or package reference.
+ *
+ * Never throws: an unusable input comes back as `kind: "invalid"` with a
+ * reason, because these strings arrive from models and users alike and a
+ * parser that throws on hostile input is a denial-of-service in the turn loop.
+ */
+export declare function parseAgentFqn(raw: string): AgentFqn;
+/** Render a parsed reference back to its canonical string, for display. */
+export declare function formatAgentFqn(fqn: AgentFqn): string;
+//# sourceMappingURL=agent-fqn.d.ts.map

package/dist/agent-fqn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-fqn.d.ts","sourceRoot":"","sources":["../src/agent-fqn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C,gEAAgE;AAChE,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAUD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CA0DnD;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAYpD"}