pilotswarm-sdk 0.5.30 → 0.5.32

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/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"}

package/dist/agent-fqn.js

@@ -0,0 +1,137 @@
+/**
+ * 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 const SHARED_SENTINEL = "__shared";
+/** Any name starting with this is reserved for the platform. */
+export const RESERVED_PREFIX = "__";
+/**
+ * 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 function isReservedName(value) {
+    return String(value ?? "").trim().toLowerCase().startsWith(RESERVED_PREFIX);
+}
+/**
+ * A semver as this system uses it: `X.Y.Z` with optional pre-release/build.
+ * Deliberately strict — the third segment of an FQN is only treated as a
+ * version when it unmistakably IS one, so `a:b:c` with a non-version tail
+ * stays invalid rather than silently resolving to something else.
+ */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function isSemver(value) {
+    return SEMVER_RE.test(String(value ?? "").trim());
+}
+const invalid = (reason) => ({ kind: "invalid", name: "", reason });
+/**
+ * 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 function parseAgentFqn(raw) {
+    // Reject non-strings rather than coercing. `String(123)` would parse as
+    // the perfectly valid bare name "123", and `String({})` as
+    // "[object Object]" — both of which hide a caller bug behind a name that
+    // looks legitimate all the way down to the database.
+    if (typeof raw !== "string")
+        return invalid("name must be a string");
+    const text = raw.trim();
+    if (!text)
+        return invalid("empty name");
+    const parts = text.split(":");
+    if (parts.some((p) => p.trim() === "")) {
+        // Catches ":x", "x:", "a::b" — all of which would otherwise produce a
+        // silently empty segment and resolve to something unintended.
+        return invalid(`malformed qualified name "${text}": empty segment`);
+    }
+    if (parts.length > 3) {
+        return invalid(`malformed qualified name "${text}": too many segments`);
+    }
+    if (parts.length === 1) {
+        const name = parts[0];
+        if (isReservedName(name)) {
+            return invalid(`"${name}" uses the reserved "${RESERVED_PREFIX}" prefix`);
+        }
+        return { kind: "bare", name };
+    }
+    const [first, second, third] = parts;
+    // A reserved first segment is unambiguous by construction.
+    if (isReservedName(first)) {
+        if (first.toLowerCase() !== SHARED_SENTINEL) {
+            return invalid(`"${first}" is a reserved namespace and is not recognized`);
+        }
+        if (isReservedName(second)) {
+            return invalid(`"${second}" uses the reserved "${RESERVED_PREFIX}" prefix`);
+        }
+        if (parts.length === 3) {
+            if (!isSemver(third))
+                return invalid(`"${third}" is not a valid semver`);
+            return { kind: "shared", name: second, semver: third };
+        }
+        return { kind: "shared", name: second };
+    }
+    if (isReservedName(second)) {
+        return invalid(`"${second}" uses the reserved "${RESERVED_PREFIX}" prefix`);
+    }
+    // Three segments end in a semver — a shape namespaces never had, so this
+    // is unambiguously an FQN.
+    if (parts.length === 3) {
+        if (!isSemver(third))
+            return invalid(`"${third}" is not a valid semver`);
+        return { kind: "owner", name: second, ownerRef: first, semver: third };
+    }
+    // Two segments: genuinely both readings. Report both and let the resolver
+    // apply its documented order rather than guessing here.
+    return { kind: "ambiguous", name: second, ownerRef: first, namespaceRef: first };
+}
+/** Render a parsed reference back to its canonical string, for display. */
+export function formatAgentFqn(fqn) {
+    switch (fqn.kind) {
+        case "bare":
+            return fqn.name;
+        case "shared":
+            return `${SHARED_SENTINEL}:${fqn.name}${fqn.semver ? `:${fqn.semver}` : ""}`;
+        case "owner":
+        case "ambiguous":
+            return `${fqn.ownerRef}:${fqn.name}${fqn.semver ? `:${fqn.semver}` : ""}`;
+        default:
+            return "";
+    }
+}
+//# sourceMappingURL=agent-fqn.js.map

package/dist/agent-fqn.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"agent-loader.d.ts","sourceRoot":"","sources":["../src/agent-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAclF;AAID,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qHAAqH;IACrH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,WAAW,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;IAC/E;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAuJD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CA6E/D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAYhD"}
+{"version":3,"file":"agent-loader.d.ts","sourceRoot":"","sources":["../src/agent-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAclF;AAID,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qHAAqH;IACrH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,WAAW,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;IAC/E;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAyKD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CA6E/D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAYhD"}

package/dist/agent-loader.js

@@ -61,6 +61,15 @@ export function systemChildAgentUUID(parentSessionId, slug) {
     ].join("-");
 }
 // ─── Frontmatter Parser ─────────────────────────────────────────
+/**
+ * Keys whose value may be a YAML block scalar (`|` literal, `>` folded).
+ *
+ * `description` belongs here because a multi-line description is the natural
+ * way to write one, and the failure is silent: the value lands as the literal
+ * "|" and the indented body is dropped on the floor. That shipped — the Agent
+ * Manager's description read "|" in every picker and listing.
+ */
+const BLOCK_SCALAR_KEYS = new Set(["splash", "splashMobile", "initialPrompt", "description"]);
 /**
  * Parse YAML frontmatter from an .agent.md file.
  * Handles simple `key: value` pairs and YAML list syntax for `tools` and `skills`.
@@ -90,6 +99,11 @@ function parseAgentFrontmatter(content) {
                 // For > (folded) scalars, collapse newlines to spaces
                 meta.initialPrompt = currentBlockStyle === ">" ? val.replace(/\n/g, " ").trim() : val;
             }
+            else if (currentKey === "description") {
+                // A description is one paragraph wherever it is displayed, so
+                // both styles collapse to a single line.
+                meta.description = val.replace(/\n/g, " ").trim();
+            }
             multilineValue = null;
             currentBlockStyle = null;
         }
@@ -151,7 +165,14 @@ function parseAgentFrontmatter(content) {
             value = value.slice(1, -1);
         }
         currentKey = key;
-        if (key === "name")
+        // Block scalars are detected before the per-key branches below: those
+        // assign `value` verbatim, so a `key: |` reaching them would store the
+        // literal "|" and orphan the indented lines that follow.
+        if (BLOCK_SCALAR_KEYS.has(key) && (value === "|" || value === ">")) {
+            currentBlockStyle = value;
+            multilineValue = [];
+        }
+        else if (key === "name")
             meta.name = value;
         else if (key === "description")
             meta.description = value;
@@ -198,11 +219,6 @@ function parseAgentFrontmatter(content) {
         else if (key === "inheritDefaultMcpServers") {
             meta.inheritDefaultMcpServers = value === "true";
         }
-        else if ((key === "splash" || key === "splashMobile" || key === "initialPrompt") && (value === "|" || value === ">")) {
-            // YAML block scalar (| literal, > folded)
-            currentBlockStyle = value;
-            multilineValue = [];
-        }
         else if (key === "splash") {
             meta.splash = value;
         }