@openscout/protocol 0.2.63 → 0.2.82

package/dist/native-interactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-interactions.d.ts","sourceRoot":"","sources":["../src/native-interactions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,4BAA4B,GACpC,UAAU,GACV,eAAe,GACf,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,WAAW,GACX,OAAO,CAAC;AAEZ,MAAM,MAAM,gCAAgC,GACxC,UAAU,GACV,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,SAAS,GACT,oBAAoB,CAAC;AAEzB,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,4BAA4B,CAAC;IACnC,MAAM,EAAE,8BAA8B,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,4BAA4B,CAAC;IACnC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,gCAAgC,EAAE,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,2CAA2C,EAAE,SAAS,+BAA+B,EA2CxF,CAAC;AAEX,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,4BAA4B,GACjC,gCAAgC,EAAE,CAEpC;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,4BAA4B,GAAG,SAAS,CAGzG"}

package/dist/native-interactions.js

@@ -0,0 +1,51 @@
+export const DEFAULT_HARNESS_NATIVE_INTERACTION_MAPPINGS = [
+    {
+        kind: "question",
+        nativeNames: ["ask_user"],
+        scoutTargets: ["question", "session_projection"],
+        description: "A harness-native user question becomes a Scout question.",
+    },
+    {
+        kind: "plan_approval",
+        nativeNames: ["submit_plan"],
+        scoutTargets: ["work_item", "session_projection"],
+        description: "A harness-native plan review becomes a Scout work item or review-needed projection.",
+    },
+    {
+        kind: "task_projection",
+        nativeNames: ["task_write", "task_update", "task_complete", "task_check"],
+        scoutTargets: ["work_item", "session_projection"],
+        description: "Harness-native task tools project into Scout work item task state.",
+    },
+    {
+        kind: "subagent_activity",
+        nativeNames: ["subagent"],
+        scoutTargets: ["invocation", "flight", "session_projection"],
+        description: "Harness-native child agent activity links to child invocations or observed child runs.",
+    },
+    {
+        kind: "tool_approval",
+        nativeNames: ["tool_approval_required"],
+        scoutTargets: ["session_projection"],
+        description: "A harness-native tool approval projects into session state.",
+    },
+    {
+        kind: "follow_up",
+        nativeNames: ["follow_up"],
+        scoutTargets: ["message", "session_projection"],
+        description: "A queued follow-up remains in the same conversation/session context.",
+    },
+    {
+        kind: "steer",
+        nativeNames: ["steer"],
+        scoutTargets: ["flight", "message", "session_projection"],
+        description: "A steering request redirects the active session or flight with an explicit reason.",
+    },
+];
+export function scoutTargetsForNativeInteraction(kind) {
+    return [...(DEFAULT_HARNESS_NATIVE_INTERACTION_MAPPINGS.find(mapping => mapping.kind === kind)?.scoutTargets ?? [])];
+}
+export function nativeInteractionKindForName(nativeName) {
+    const normalized = nativeName.trim();
+    return DEFAULT_HARNESS_NATIVE_INTERACTION_MAPPINGS.find(mapping => mapping.nativeNames.includes(normalized))?.kind;
+}

package/dist/observed-status.d.ts

@@ -0,0 +1,33 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+export type ObservedStatusPhase = "unconfigured" | "registered" | "starting" | "connecting" | "running" | "stopping" | "stopped" | "closed" | "error" | "unknown";
+export type ObservedActivity = "idle" | "queued" | "waking" | "thinking" | "executing" | "working" | "waiting_for_input" | "waiting_on_actor" | "blocked" | "review" | "completed" | "failed" | "cancelled" | "stalled" | "offline" | "unknown";
+export type ObservedStatusSubjectKind = "agent" | "endpoint" | "flight" | "run" | "question" | "work_item" | "pairing_runtime" | "tail_session";
+export type ObservedStatusProvenanceSource = "broker_record" | "endpoint" | "flight" | "agent_run" | "collaboration_record" | "session_trace" | "pairing_runtime" | "tail_event" | "process" | "tmux" | "staleness_inference";
+export interface ObservedStatusDetail {
+    title?: string;
+    summary?: string;
+    toolName?: string;
+    waitingOn?: unknown;
+    sourceCursor?: string;
+    metadata?: MetadataMap;
+}
+export interface StatusProjectionProvenance {
+    source: ObservedStatusProvenanceSource;
+    refId: ScoutId;
+    observedAt: number;
+    confidence: number;
+}
+export interface ObservedStatusProjection {
+    subjectKind: ObservedStatusSubjectKind;
+    subjectId: ScoutId;
+    agentId?: ScoutId;
+    phase: ObservedStatusPhase;
+    activity: ObservedActivity;
+    detail?: ObservedStatusDetail;
+    provenance: StatusProjectionProvenance[];
+    confidence: number;
+    updatedAt: number;
+    staleAt?: number;
+}
+export declare function observedStatusDisplay(status: Pick<ObservedStatusProjection, "phase" | "activity">): string;
+//# sourceMappingURL=observed-status.d.ts.map

package/dist/observed-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-status.d.ts","sourceRoot":"","sources":["../src/observed-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,SAAS,GACT,UAAU,GACV,SAAS,GACT,QAAQ,GACR,OAAO,GACP,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,WAAW,GACX,SAAS,GACT,mBAAmB,GACnB,kBAAkB,GAClB,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,WAAW,GACX,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,MAAM,yBAAyB,GACjC,OAAO,GACP,UAAU,GACV,QAAQ,GACR,KAAK,GACL,UAAU,GACV,WAAW,GACX,iBAAiB,GACjB,cAAc,CAAC;AAEnB,MAAM,MAAM,8BAA8B,GACtC,eAAe,GACf,UAAU,GACV,QAAQ,GACR,WAAW,GACX,sBAAsB,GACtB,eAAe,GACf,iBAAiB,GACjB,YAAY,GACZ,SAAS,GACT,MAAM,GACN,qBAAqB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,8BAA8B,CAAC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,yBAAyB,CAAC;IACvC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,UAAU,EAAE,0BAA0B,EAAE,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,MAAM,CAK1G"}

package/dist/observed-status.js

@@ -0,0 +1,6 @@
+export function observedStatusDisplay(status) {
+    if (status.phase === "running" && status.activity && status.activity !== "unknown") {
+        return status.activity;
+    }
+    return status.phase;
+}

package/dist/orchestrator-prompt.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Soft-mode prompt fragment for agents with an active orchestrator assignment.
+ * Inject into the agent system/tool preamble when assignment is present.
+ */
+import { type ScoutRoleAssignment } from "./assigned-roles.js";
+export declare function orchestratorSoftPrompt(opts: {
+    assignment: ScoutRoleAssignment;
+    missionId?: string;
+}): string;
+//# sourceMappingURL=orchestrator-prompt.d.ts.map

package/dist/orchestrator-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-prompt.d.ts","sourceRoot":"","sources":["../src/orchestrator-prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAE7B,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,UAAU,EAAE,mBAAmB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAgCT"}

package/dist/orchestrator-prompt.js

@@ -0,0 +1,36 @@
+/**
+ * Soft-mode prompt fragment for agents with an active orchestrator assignment.
+ * Inject into the agent system/tool preamble when assignment is present.
+ */
+import { SCOUT_MISSION_LOG_LIMITS, SCOUT_ORCHESTRATOR_ROLE, } from "./assigned-roles.js";
+export function orchestratorSoftPrompt(opts) {
+    const missionLine = opts.assignment.scope.kind === "mission"
+        ? `Mission (work id): ${opts.assignment.scope.missionId}`
+        : opts.missionId
+            ? `Active mission context: ${opts.missionId} (standing orchestrator assignment)`
+            : "Standing orchestrator: prefer mission-scoped assignment when a campaign exists.";
+    return [
+        `# Orchestrator role (assigned)`,
+        "",
+        `You are assigned the **${SCOUT_ORCHESTRATOR_ROLE.label}** role.`,
+        SCOUT_ORCHESTRATOR_ROLE.summary,
+        missionLine,
+        "",
+        "## Duties",
+        "- Own the mission spine: keep child work/asks linked under the campaign root.",
+        "- On mission moments (turn end, delegation, waiting, finish), append a short mission log entry.",
+        "- When blocked, set who holds the next move.",
+        "- Do not spam: only mission-level moments, not every tool call.",
+        "",
+        "## Mission log fields",
+        `- intent: stable goal (≤ ${SCOUT_MISSION_LOG_LIMITS.intentMaxWords} words)`,
+        `- status: current action (≤ ${SCOUT_MISSION_LOG_LIMITS.statusMaxWords} words)`,
+        `- kind: heartbeat | progress | delegation | waiting | decision | risk | integration | done | failed`,
+        `- note: optional, ≤ ${SCOUT_MISSION_LOG_LIMITS.noteMaxChars} chars`,
+        "",
+        "## How to write",
+        "- CLI: `scout role log-append <missionId> --actor <you> --kind progress --intent \"...\" --status \"...\"`",
+        "- HTTP: `POST /api/missions/<missionId>/log` with actorId, kind, intent, status",
+        "- Verbose chat stays in DMs; mission log is the cheap reconstruction stream.",
+    ].join("\n");
+}

package/dist/permission-policy.d.ts

@@ -0,0 +1,5 @@
+export declare const SCOUT_PERMISSION_PROFILES: readonly ["observe", "review", "workspace_write", "sandboxed_write", "trusted_local", "external_sandbox"];
+export type ScoutPermissionProfile = typeof SCOUT_PERMISSION_PROFILES[number];
+export declare function normalizeScoutPermissionProfile(value: string | null | undefined): ScoutPermissionProfile | undefined;
+export declare function formatScoutPermissionProfiles(): string;
+//# sourceMappingURL=permission-policy.d.ts.map

package/dist/permission-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-policy.d.ts","sourceRoot":"","sources":["../src/permission-policy.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,2GAO5B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,OAAO,yBAAyB,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,sBAAsB,GAAG,SAAS,CAGpC;AAED,wBAAgB,6BAA6B,IAAI,MAAM,CAEtD"}

package/dist/permission-policy.js

@@ -0,0 +1,15 @@
+export const SCOUT_PERMISSION_PROFILES = [
+    "observe",
+    "review",
+    "workspace_write",
+    "sandboxed_write",
+    "trusted_local",
+    "external_sandbox",
+];
+export function normalizeScoutPermissionProfile(value) {
+    const normalized = value?.trim().replaceAll("-", "_");
+    return SCOUT_PERMISSION_PROFILES.find((profile) => profile === normalized);
+}
+export function formatScoutPermissionProfiles() {
+    return SCOUT_PERMISSION_PROFILES.join("|");
+}

package/dist/provisional-agent-names.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Curated rotation pool for provisional agent identities.
+ *
+ * Names are short, human-addressable, and collision-resistant across a local
+ * fleet. Categories include scientists, composers, philosophers, and a few
+ * literary figures — chosen for memorability, not biographical endorsement.
+ */
+export declare const PROVISIONAL_AGENT_NAMES: readonly ["archimedes", "avogadro", "bohr", "boyle", "copernicus", "curie", "dalton", "darwin", "dirac", "einstein", "euler", "faraday", "feynman", "fermi", "fourier", "galileo", "gauss", "hawking", "heisenberg", "hooke", "hopper", "hypatia", "kepler", "lavoisier", "lovelace", "maxwell", "mendel", "newton", "noether", "oppenheimer", "pasteur", "pauli", "planck", "pythagoras", "rutherford", "sagan", "turing", "volterra", "bach", "bartok", "beethoven", "brahms", "chopin", "debussy", "dvorak", "grieg", "handel", "haydn", "liszt", "mahler", "monteverdi", "mozart", "prokofiev", "purcell", "ravel", "satie", "schubert", "schumann", "stravinsky", "tchaikovsky", "vivaldi", "wagner", "aquinas", "aristotle", "confucius", "descartes", "epicurus", "hegel", "hume", "kant", "kierkegaard", "locke", "machiavelli", "nietzsche", "plato", "popper", "rousseau", "russell", "seneca", "socrates", "spinoza", "voltaire", "wittgenstein", "zeno", "austen", "borges", "dickens", "dostoevsky", "homer", "kafka", "orwell", "shakespeare", "tolstoy", "virgil", "woolf", "atlas", "cobalt", "drover", "hudson", "pike", "quill"];
+export type ProvisionalAgentName = (typeof PROVISIONAL_AGENT_NAMES)[number];
+export declare function normalizeProvisionalAgentNameCandidates(candidates: Iterable<string>): string[];
+export declare function parseProvisionalAgentNamesText(content: string): string[];
+export declare function parseProvisionalAgentNamesJson(content: string): string[];
+export declare function isProvisionalAgentName(value: string, pool?: readonly string[]): boolean;
+/** Extract the base definition id from an agent id, handle, or @label. */
+export declare function definitionIdFromOccupancyKey(value: string): string | null;
+export declare function collectOccupiedDefinitionIds(references: Iterable<string>): Set<string>;
+export type AllocateProvisionalAgentNameOptions = {
+    /** When set, allocation starts scanning from this pool index (wraps). */
+    startIndex?: number;
+    /** Override the built-in pool (for example operator-configured names). */
+    pool?: readonly string[];
+};
+export type ProvisionalAgentNameSeedPart = string | number | boolean | null | undefined;
+export declare function provisionalAgentNameStartIndexForSeed(seedParts: Iterable<ProvisionalAgentNameSeedPart>, pool?: readonly string[]): number;
+/**
+ * Pick the next free name from the pool.
+ * Falls back to `{poolName}-{n}` only when the entire pool is occupied.
+ */
+export declare function allocateProvisionalAgentName(occupied: ReadonlySet<string> | Iterable<string>, options?: AllocateProvisionalAgentNameOptions): string;
+//# sourceMappingURL=provisional-agent-names.d.ts.map

package/dist/provisional-agent-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisional-agent-names.d.ts","sourceRoot":"","sources":["../src/provisional-agent-names.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,olCA2G1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,wBAAgB,uCAAuC,CACrD,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC3B,MAAM,EAAE,CAcV;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAExE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAqBxE;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAS,MAAM,EAA4B,GAChD,OAAO,CAGT;AAED,0EAA0E;AAC1E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczE;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAStF;AAED,MAAM,MAAM,mCAAmC,GAAG;IAChD,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAWxF,wBAAgB,qCAAqC,CACnD,SAAS,EAAE,QAAQ,CAAC,4BAA4B,CAAC,EACjD,IAAI,GAAE,SAAS,MAAM,EAA4B,GAChD,MAAM,CAgBR;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,EAChD,OAAO,GAAE,mCAAwC,GAChD,MAAM,CAwBR"}

package/dist/provisional-agent-names.js

@@ -0,0 +1,224 @@
+import { normalizeAgentSelectorSegment, parseAgentIdentity } from "./agent-identity.js";
+/**
+ * Curated rotation pool for provisional agent identities.
+ *
+ * Names are short, human-addressable, and collision-resistant across a local
+ * fleet. Categories include scientists, composers, philosophers, and a few
+ * literary figures — chosen for memorability, not biographical endorsement.
+ */
+export const PROVISIONAL_AGENT_NAMES = [
+    // Scientists & inventors
+    "archimedes",
+    "avogadro",
+    "bohr",
+    "boyle",
+    "copernicus",
+    "curie",
+    "dalton",
+    "darwin",
+    "dirac",
+    "einstein",
+    "euler",
+    "faraday",
+    "feynman",
+    "fermi",
+    "fourier",
+    "galileo",
+    "gauss",
+    "hawking",
+    "heisenberg",
+    "hooke",
+    "hopper",
+    "hypatia",
+    "kepler",
+    "lavoisier",
+    "lovelace",
+    "maxwell",
+    "mendel",
+    "newton",
+    "noether",
+    "oppenheimer",
+    "pasteur",
+    "pauli",
+    "planck",
+    "pythagoras",
+    "rutherford",
+    "sagan",
+    "turing",
+    "volterra",
+    // Composers
+    "bach",
+    "bartok",
+    "beethoven",
+    "brahms",
+    "chopin",
+    "debussy",
+    "dvorak",
+    "grieg",
+    "handel",
+    "haydn",
+    "liszt",
+    "mahler",
+    "monteverdi",
+    "mozart",
+    "prokofiev",
+    "purcell",
+    "ravel",
+    "satie",
+    "schubert",
+    "schumann",
+    "stravinsky",
+    "tchaikovsky",
+    "vivaldi",
+    "wagner",
+    // Philosophers & thinkers
+    "aquinas",
+    "aristotle",
+    "confucius",
+    "descartes",
+    "epicurus",
+    "hegel",
+    "hume",
+    "kant",
+    "kierkegaard",
+    "locke",
+    "machiavelli",
+    "nietzsche",
+    "plato",
+    "popper",
+    "rousseau",
+    "russell",
+    "seneca",
+    "socrates",
+    "spinoza",
+    "voltaire",
+    "wittgenstein",
+    "zeno",
+    // Writers (classic, globally recognizable)
+    "austen",
+    "borges",
+    "dickens",
+    "dostoevsky",
+    "homer",
+    "kafka",
+    "orwell",
+    "shakespeare",
+    "tolstoy",
+    "virgil",
+    "woolf",
+    // House vocabulary (design-studies / product fixtures)
+    "atlas",
+    "cobalt",
+    "drover",
+    "hudson",
+    "pike",
+    "quill",
+];
+export function normalizeProvisionalAgentNameCandidates(candidates) {
+    const seen = new Set();
+    const normalizedNames = [];
+    for (const raw of candidates) {
+        const withoutComment = raw.split("#")[0]?.trim() ?? "";
+        const withoutSigil = withoutComment.replace(/^@+/, "").trim();
+        const normalized = normalizeAgentSelectorSegment(withoutSigil);
+        if (!normalized || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        normalizedNames.push(normalized);
+    }
+    return normalizedNames;
+}
+export function parseProvisionalAgentNamesText(content) {
+    return normalizeProvisionalAgentNameCandidates(content.split(/\r?\n/u));
+}
+export function parseProvisionalAgentNamesJson(content) {
+    const parsed = JSON.parse(content);
+    if (Array.isArray(parsed)) {
+        return normalizeProvisionalAgentNameCandidates(parsed.filter((entry) => typeof entry === "string"));
+    }
+    if (parsed
+        && typeof parsed === "object"
+        && Array.isArray(parsed.names)) {
+        return normalizeProvisionalAgentNameCandidates(parsed.names.filter((entry) => typeof entry === "string"));
+    }
+    throw new Error("provisional agent names JSON must be a string array or { \"names\": [...] }");
+}
+export function isProvisionalAgentName(value, pool = PROVISIONAL_AGENT_NAMES) {
+    const normalized = normalizeAgentSelectorSegment(value);
+    return normalized.length > 0 && pool.includes(normalized);
+}
+/** Extract the base definition id from an agent id, handle, or @label. */
+export function definitionIdFromOccupancyKey(value) {
+    const trimmed = value.trim().replace(/^@+/, "");
+    if (!trimmed) {
+        return null;
+    }
+    const parsed = parseAgentIdentity(trimmed.startsWith("@") ? trimmed : `@${trimmed}`);
+    if (parsed?.definitionId) {
+        return normalizeAgentSelectorSegment(parsed.definitionId);
+    }
+    const head = trimmed.split(".")[0]?.trim() ?? "";
+    const normalized = normalizeAgentSelectorSegment(head);
+    return normalized || null;
+}
+export function collectOccupiedDefinitionIds(references) {
+    const occupied = new Set();
+    for (const reference of references) {
+        const definitionId = definitionIdFromOccupancyKey(reference);
+        if (definitionId) {
+            occupied.add(definitionId);
+        }
+    }
+    return occupied;
+}
+function updateFnv1a32(hash, value) {
+    let next = hash >>> 0;
+    for (let index = 0; index < value.length; index += 1) {
+        next ^= value.charCodeAt(index);
+        next = Math.imul(next, 0x01000193) >>> 0;
+    }
+    return next;
+}
+export function provisionalAgentNameStartIndexForSeed(seedParts, pool = PROVISIONAL_AGENT_NAMES) {
+    if (pool.length === 0) {
+        return 0;
+    }
+    let hash = 0x811c9dc5;
+    let fieldIndex = 0;
+    for (const part of seedParts) {
+        const value = part == null ? "" : String(part);
+        hash = updateFnv1a32(hash, `${fieldIndex}:${value.length}:`);
+        hash = updateFnv1a32(hash, value);
+        hash = updateFnv1a32(hash, "|");
+        fieldIndex += 1;
+    }
+    hash = updateFnv1a32(hash, `fields:${fieldIndex}`);
+    return hash % pool.length;
+}
+/**
+ * Pick the next free name from the pool.
+ * Falls back to `{poolName}-{n}` only when the entire pool is occupied.
+ */
+export function allocateProvisionalAgentName(occupied, options = {}) {
+    const pool = options.pool?.length ? options.pool : PROVISIONAL_AGENT_NAMES;
+    if (pool.length === 0) {
+        throw new Error("provisional agent name pool is empty");
+    }
+    const taken = occupied instanceof Set
+        ? occupied
+        : collectOccupiedDefinitionIds(occupied);
+    const start = Math.abs(options.startIndex ?? 0) % pool.length;
+    for (let offset = 0; offset < pool.length; offset += 1) {
+        const candidate = pool[(start + offset) % pool.length];
+        if (!taken.has(candidate)) {
+            return candidate;
+        }
+    }
+    const anchor = pool[start];
+    let suffix = 2;
+    while (taken.has(`${anchor}-${suffix}`)) {
+        suffix += 1;
+    }
+    return `${anchor}-${suffix}`;
+}

package/dist/read-receipts.d.ts

@@ -0,0 +1,12 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+export interface ConversationReadCursor {
+    conversationId: ScoutId;
+    actorId: ScoutId;
+    readerNodeId?: ScoutId;
+    lastReadMessageId?: ScoutId;
+    lastReadSeq?: number;
+    lastReadAt: number;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+//# sourceMappingURL=read-receipts.d.ts.map

package/dist/read-receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-receipts.d.ts","sourceRoot":"","sources":["../src/read-receipts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB"}

package/dist/read-receipts.js

@@ -0,0 +1 @@
+export {};

package/dist/relay-agent-card.d.ts

@@ -13,6 +13,14 @@ export interface RelayReturnAddress {
     sessionId?: string;
     metadata?: MetadataMap;
 }
+export interface RelayAgentCardLifecycle {
+    kind: "persistent" | "one_time";
+    createdAt?: number;
+    createdById?: ScoutId;
+    expiresAt?: number;
+    maxUses?: number;
+    inboxConversationId?: ScoutId;
+}
 export interface RelayAgentCard {
     id: ScoutId;
     agentId: ScoutId;
@@ -32,7 +40,9 @@ export interface RelayAgentCard {
     createdById?: ScoutId;
     brokerRegistered: boolean;
     inboxConversationId?: ScoutId;
+    lifecycle?: RelayAgentCardLifecycle;
     returnAddress: RelayReturnAddress;
     metadata?: MetadataMap;
 }
 export declare function buildRelayReturnAddress(input: RelayReturnAddress): RelayReturnAddress;
+//# sourceMappingURL=relay-agent-card.d.ts.map

package/dist/relay-agent-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-agent-card.d.ts","sourceRoot":"","sources":["../src/relay-agent-card.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,YAAY,GAAG,UAAU,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,aAAa,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,kBAAkB,CAiCrF"}

package/dist/rendezvous.d.ts

@@ -0,0 +1,97 @@
+import type { ScoutId } from "./common.js";
+export declare const SCOUT_RENDEZVOUS_GENERATED_CODENAME_LENGTH = 6;
+export declare const SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH = 32;
+export declare const SCOUT_RENDEZVOUS_INVITE_TTL_MS: number;
+export declare const SCOUT_RENDEZVOUS_MAX_WAIT_MS: number;
+export type ScoutRendezvousCreateRequest = {
+    action: "create";
+    codename?: string;
+    projectRoot: string;
+    participantId: ScoutId;
+};
+export type ScoutRendezvousJoinRequest = {
+    action: "join";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    waitMs?: number;
+};
+export type ScoutRendezvousRequest = ScoutRendezvousCreateRequest | ScoutRendezvousJoinRequest;
+export type ScoutRendezvousCreatedResponse = {
+    status: "created";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    createdAt: number;
+    expiresAt: number;
+};
+export type ScoutRendezvousWaitingResponse = {
+    status: "waiting";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    joinedAt: number;
+    expiresAt: number;
+};
+export type ScoutRendezvousMatchedResponse = {
+    status: "matched";
+    matchId: ScoutId;
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    participantIds: [ScoutId, ScoutId];
+    peerParticipantIds: ScoutId[];
+    createdAt: number;
+    expiresAt: number;
+};
+export type ScoutRendezvousCodenameBusyResponse = {
+    status: "codename_busy";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    participantCount: number;
+    expiresAt: number;
+    suggestion: "choose_another_codename";
+};
+export type ScoutRendezvousNotFoundResponse = {
+    status: "not_found";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    suggestion: "check_codename_or_create";
+};
+export type ScoutRendezvousExpiredResponse = {
+    status: "expired";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    expiresAt: number;
+    suggestion: "choose_another_codename";
+};
+export type ScoutRendezvousConsumedResponse = {
+    status: "consumed";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    expiresAt: number;
+    suggestion: "choose_another_codename";
+};
+export type ScoutRendezvousProjectMismatchResponse = {
+    status: "project_mismatch";
+    codename: string;
+    projectRoot: string;
+    participantId: ScoutId;
+    suggestion: "run_in_invitation_project";
+};
+export type ScoutRendezvousResponse = ScoutRendezvousCreatedResponse | ScoutRendezvousWaitingResponse | ScoutRendezvousMatchedResponse | ScoutRendezvousCodenameBusyResponse | ScoutRendezvousNotFoundResponse | ScoutRendezvousExpiredResponse | ScoutRendezvousConsumedResponse | ScoutRendezvousProjectMismatchResponse;
+export type ScoutRendezvousFailureResponse = Extract<ScoutRendezvousResponse, {
+    status: "codename_busy" | "not_found" | "expired" | "consumed" | "project_mismatch";
+}>;
+export declare function isScoutRendezvousFailureResponse(response: ScoutRendezvousResponse): response is ScoutRendezvousFailureResponse;
+export declare function normalizeScoutRendezvousCodename(codename: string): string;
+/**
+ * Validates a human-chosen codename while retaining its display capitalization.
+ * Case folding is only for broker lookup keys.
+ */
+export declare function validateScoutRendezvousCodename(codename: unknown): string;
+//# sourceMappingURL=rendezvous.d.ts.map

package/dist/rendezvous.d.ts.map

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

package/dist/rendezvous.js

@@ -0,0 +1,35 @@
+export const SCOUT_RENDEZVOUS_GENERATED_CODENAME_LENGTH = 6;
+export const SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH = 32;
+// Rooms stay joinable for hours so a human can relay the codename to the
+// second session at their own pace; per-call long-polls stay short.
+export const SCOUT_RENDEZVOUS_INVITE_TTL_MS = 4 * 60 * 60_000;
+export const SCOUT_RENDEZVOUS_MAX_WAIT_MS = 10 * 60_000;
+export function isScoutRendezvousFailureResponse(response) {
+    return response.status === "codename_busy"
+        || response.status === "not_found"
+        || response.status === "expired"
+        || response.status === "consumed"
+        || response.status === "project_mismatch";
+}
+export function normalizeScoutRendezvousCodename(codename) {
+    return codename.normalize("NFKC").trim().toLocaleUpperCase("en-US");
+}
+/**
+ * Validates a human-chosen codename while retaining its display capitalization.
+ * Case folding is only for broker lookup keys.
+ */
+export function validateScoutRendezvousCodename(codename) {
+    if (typeof codename !== "string") {
+        throw new Error("codename must be a string");
+    }
+    const displayCodename = codename.normalize("NFKC").trim();
+    if (!displayCodename) {
+        throw new Error("codename must not be blank");
+    }
+    const normalized = normalizeScoutRendezvousCodename(displayCodename);
+    if (normalized.length > SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH
+        || !/^[A-Z0-9]+$/u.test(normalized)) {
+        throw new Error(`codename must be 1 to ${SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH} ASCII letters or digits`);
+    }
+    return displayCodename;
+}