@openscout/protocol 0.1.0 → 0.2.2

package/README.md

@@ -89,7 +89,7 @@ This lets a person work with a helper in Codex or Claude while still invoking re
 
 The intended machine lifecycle is:
 
-1. `scout init` creates machine-local settings, a relay agent registry, and repo-local `.openscout/project.json` when needed.
+1. `scout setup` creates machine-local settings, a relay agent registry, and repo-local `.openscout/project.json` when needed.
 2. The runtime installs a launch agent under `~/Library/LaunchAgents/` for the broker.
 3. `launchd` keeps the broker process alive and restarts it if it exits.
 4. Workspace discovery scans configured roots and repo-local manifests to map projects to agent identities.

package/dist/agent-address.d.ts

@@ -0,0 +1 @@
+export * from "./agent-identity.js";

package/dist/agent-address.js

@@ -0,0 +1 @@
+export * from "./agent-identity.js";

package/dist/agent-identity.d.ts

@@ -0,0 +1,69 @@
+import type { ScoutId } from "./common.js";
+export type AgentIdentityDimension = "workspace" | "profile" | "harness" | "node";
+export interface AgentIdentity {
+    raw: string;
+    label: string;
+    definitionId: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+    profile?: string;
+    harness?: string;
+}
+export interface AgentIdentityCandidate {
+    agentId: ScoutId;
+    definitionId?: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+    profile?: string;
+    harness?: string;
+    aliases?: string[];
+}
+export interface AgentIdentityInput {
+    definitionId: ScoutId;
+    nodeQualifier?: string;
+    workspaceQualifier?: string;
+    profile?: string;
+    harness?: string;
+}
+export interface AgentIdentityAlias {
+    alias: string;
+    target: AgentIdentityInput;
+}
+export declare function normalizeAgentIdentitySegment(value: string): string;
+export declare const normalizeAgentSelectorSegment: typeof normalizeAgentIdentitySegment;
+export declare function parseAgentIdentity(value: string): AgentIdentity | null;
+export declare function formatAgentIdentity(input: AgentIdentityInput, options?: {
+    includeSigil?: boolean;
+}): string;
+export declare function constructAgentIdentity(input: AgentIdentityInput, options?: {
+    raw?: string;
+}): AgentIdentity | null;
+export declare function extractAgentIdentities(text: string): AgentIdentity[];
+export declare function agentIdentityMatches(identity: AgentIdentity, candidate: AgentIdentityCandidate): boolean;
+export declare function resolveAgentIdentity<T extends AgentIdentityCandidate>(identity: AgentIdentity, candidates: T[]): T | null;
+export declare function constructAgentAlias(input: {
+    alias: string;
+    target: AgentIdentityInput;
+}): AgentIdentityAlias | null;
+export declare function formatAgentAlias(alias: AgentIdentityAlias, options?: {
+    includeSigil?: boolean;
+}): string;
+export declare function resolveAgentAlias(value: string, aliases: AgentIdentityAlias[]): AgentIdentity | null;
+export declare function formatMinimalAgentIdentity<T extends AgentIdentityCandidate>(candidate: T, candidates: T[], options?: {
+    includeSigil?: boolean;
+}): string;
+export type AgentAddress = AgentIdentity;
+export type AgentAddressCandidate = AgentIdentityCandidate;
+export type AgentSelector = AgentIdentity;
+export type AgentSelectorCandidate = AgentIdentityCandidate;
+export declare const parseAgentAddress: typeof parseAgentIdentity;
+export declare const formatAgentAddress: typeof formatAgentIdentity;
+export declare const constructAgentAddress: typeof constructAgentIdentity;
+export declare const extractAgentAddresses: typeof extractAgentIdentities;
+export declare const agentAddressMatches: typeof agentIdentityMatches;
+export declare const resolveAgentAddress: typeof resolveAgentIdentity;
+export declare const parseAgentSelector: typeof parseAgentIdentity;
+export declare const formatAgentSelector: typeof formatAgentIdentity;
+export declare const extractAgentSelectors: typeof extractAgentIdentities;
+export declare const agentSelectorMatches: typeof agentIdentityMatches;
+export declare const resolveAgentSelector: typeof resolveAgentIdentity;

package/dist/agent-identity.js

@@ -0,0 +1,369 @@
+const DIMENSION_ALIASES = {
+    workspace: "workspace",
+    worktree: "workspace",
+    branch: "workspace",
+    profile: "profile",
+    persona: "profile",
+    harness: "harness",
+    runtime: "harness",
+    node: "node",
+    host: "node",
+};
+function trimIdentityPrefix(value) {
+    return value
+        .trim()
+        .replace(/^@+/, "")
+        .replace(/[.,!?;)\]]+$/, "");
+}
+export function normalizeAgentIdentitySegment(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
+function normalizeDimensionKey(value) {
+    return DIMENSION_ALIASES[normalizeAgentIdentitySegment(value)] ?? null;
+}
+function canonicalizeIdentity(input) {
+    const definitionId = normalizeAgentIdentitySegment(input.definitionId);
+    const workspaceQualifier = input.workspaceQualifier
+        ? normalizeAgentIdentitySegment(input.workspaceQualifier)
+        : undefined;
+    const profile = input.profile ? normalizeAgentIdentitySegment(input.profile) : undefined;
+    const harness = input.harness ? normalizeAgentIdentitySegment(input.harness) : undefined;
+    const nodeQualifier = input.nodeQualifier
+        ? normalizeAgentIdentitySegment(input.nodeQualifier)
+        : undefined;
+    if (!definitionId) {
+        return null;
+    }
+    return {
+        definitionId,
+        ...(workspaceQualifier ? { workspaceQualifier } : {}),
+        ...(profile ? { profile } : {}),
+        ...(harness ? { harness } : {}),
+        ...(nodeQualifier ? { nodeQualifier } : {}),
+    };
+}
+function parseSegmentedIdentity(raw) {
+    const parts = raw.split(".").filter(Boolean);
+    const definitionPart = parts.shift();
+    if (!definitionPart) {
+        return null;
+    }
+    const next = {
+        definitionId: definitionPart,
+    };
+    let sawPositionalWorkspace = false;
+    for (const part of parts) {
+        if (part.includes(":")) {
+            const [rawKey, rawValue = ""] = part.split(":", 2);
+            const key = normalizeDimensionKey(rawKey);
+            const value = normalizeAgentIdentitySegment(rawValue);
+            if (!key || !value) {
+                return null;
+            }
+            if (key === "workspace") {
+                next.workspaceQualifier = value;
+            }
+            else if (key === "profile") {
+                next.profile = value;
+            }
+            else if (key === "harness") {
+                next.harness = value;
+            }
+            else if (key === "node") {
+                next.nodeQualifier = value;
+            }
+            continue;
+        }
+        if (sawPositionalWorkspace) {
+            return null;
+        }
+        const value = normalizeAgentIdentitySegment(part);
+        if (!value) {
+            return null;
+        }
+        next.workspaceQualifier = value;
+        sawPositionalWorkspace = true;
+    }
+    return constructAgentIdentity(next, { raw });
+}
+export function parseAgentIdentity(value) {
+    const raw = trimIdentityPrefix(value);
+    if (!raw) {
+        return null;
+    }
+    if (raw.includes("@") || raw.includes("#")) {
+        return null;
+    }
+    return parseSegmentedIdentity(raw);
+}
+export function formatAgentIdentity(input, options = {}) {
+    const canonical = canonicalizeIdentity(input);
+    if (!canonical) {
+        return options.includeSigil === false ? "" : "@";
+    }
+    const prefix = options.includeSigil === false ? "" : "@";
+    const segments = [`${prefix}${canonical.definitionId}`];
+    if (canonical.workspaceQualifier) {
+        segments.push(canonical.workspaceQualifier);
+    }
+    if (canonical.profile) {
+        segments.push(`profile:${canonical.profile}`);
+    }
+    if (canonical.harness) {
+        segments.push(`harness:${canonical.harness}`);
+    }
+    if (canonical.nodeQualifier) {
+        segments.push(`node:${canonical.nodeQualifier}`);
+    }
+    return segments.join(".");
+}
+export function constructAgentIdentity(input, options = {}) {
+    const canonical = canonicalizeIdentity(input);
+    if (!canonical) {
+        return null;
+    }
+    return {
+        raw: options.raw ?? formatAgentIdentity(canonical, { includeSigil: false }),
+        label: formatAgentIdentity(canonical),
+        definitionId: canonical.definitionId,
+        ...(canonical.nodeQualifier ? { nodeQualifier: canonical.nodeQualifier } : {}),
+        ...(canonical.workspaceQualifier ? { workspaceQualifier: canonical.workspaceQualifier } : {}),
+        ...(canonical.profile ? { profile: canonical.profile } : {}),
+        ...(canonical.harness ? { harness: canonical.harness } : {}),
+    };
+}
+export function extractAgentIdentities(text) {
+    const matches = Array.from(text.matchAll(/(^|\s)@([a-z0-9][a-z0-9._/:-]*)/gi));
+    const identities = new Map();
+    for (const match of matches) {
+        const candidate = parseAgentIdentity(match[2] ?? "");
+        if (!candidate) {
+            continue;
+        }
+        identities.set(candidate.label, candidate);
+    }
+    return Array.from(identities.values());
+}
+function candidateAliases(candidate) {
+    const canonical = canonicalizeIdentity({
+        definitionId: candidate.definitionId || candidate.agentId,
+        nodeQualifier: candidate.nodeQualifier,
+        workspaceQualifier: candidate.workspaceQualifier,
+        profile: candidate.profile,
+        harness: candidate.harness,
+    });
+    if (!canonical) {
+        return [];
+    }
+    const aliases = [
+        canonical.definitionId,
+        formatAgentIdentity(canonical),
+        canonical.workspaceQualifier
+            ? formatAgentIdentity({ definitionId: canonical.definitionId, workspaceQualifier: canonical.workspaceQualifier })
+            : "",
+        canonical.profile
+            ? formatAgentIdentity({ definitionId: canonical.definitionId, profile: canonical.profile })
+            : "",
+        canonical.harness
+            ? formatAgentIdentity({ definitionId: canonical.definitionId, harness: canonical.harness })
+            : "",
+        canonical.nodeQualifier
+            ? formatAgentIdentity({ definitionId: canonical.definitionId, nodeQualifier: canonical.nodeQualifier })
+            : "",
+        ...((candidate.aliases ?? []).map((alias) => alias.trim()).filter(Boolean)),
+    ];
+    return Array.from(new Set(aliases.map((alias) => trimIdentityPrefix(alias)).filter(Boolean)));
+}
+function explicitCandidateAliases(candidate) {
+    return Array.from(new Set((candidate.aliases ?? [])
+        .map((alias) => normalizeAgentIdentitySegment(trimIdentityPrefix(alias)))
+        .filter(Boolean)));
+}
+function canonicalizeAliasValue(value) {
+    const parsed = parseAgentIdentity(value.startsWith("@") ? value : `@${value}`);
+    if (parsed) {
+        return trimIdentityPrefix(parsed.label);
+    }
+    return normalizeAgentIdentitySegment(value);
+}
+function identityAliasKeys(identity) {
+    return Array.from(new Set([
+        trimIdentityPrefix(identity.label),
+        trimIdentityPrefix(identity.raw),
+        trimIdentityPrefix(formatAgentIdentity(identity, { includeSigil: false })),
+    ].filter(Boolean)));
+}
+function candidateCanonicalIdentity(candidate) {
+    return constructAgentIdentity({
+        definitionId: candidate.definitionId || candidate.agentId,
+        nodeQualifier: candidate.nodeQualifier,
+        workspaceQualifier: candidate.workspaceQualifier,
+        profile: candidate.profile,
+        harness: candidate.harness,
+    });
+}
+function candidateDimensionValue(candidate, dimension) {
+    const canonical = candidateCanonicalIdentity(candidate);
+    if (!canonical) {
+        return undefined;
+    }
+    if (dimension === "workspace")
+        return canonical.workspaceQualifier;
+    if (dimension === "profile")
+        return canonical.profile;
+    if (dimension === "harness")
+        return canonical.harness;
+    return canonical.nodeQualifier;
+}
+export function agentIdentityMatches(identity, candidate) {
+    const aliasKeys = identityAliasKeys(identity);
+    const candidateAliasKeys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
+    if (aliasKeys.some((key) => candidateAliasKeys.includes(key))) {
+        return true;
+    }
+    const canonical = canonicalizeIdentity({
+        definitionId: candidate.definitionId || candidate.agentId,
+        nodeQualifier: candidate.nodeQualifier,
+        workspaceQualifier: candidate.workspaceQualifier,
+        profile: candidate.profile,
+        harness: candidate.harness,
+    });
+    if (!canonical || identity.definitionId !== canonical.definitionId) {
+        return false;
+    }
+    if (identity.nodeQualifier && identity.nodeQualifier !== canonical.nodeQualifier) {
+        return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
+    }
+    if (identity.workspaceQualifier && identity.workspaceQualifier !== canonical.workspaceQualifier) {
+        return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
+    }
+    if (identity.profile && identity.profile !== canonical.profile) {
+        return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
+    }
+    if (identity.harness && identity.harness !== canonical.harness) {
+        return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
+    }
+    return true;
+}
+export function resolveAgentIdentity(identity, candidates) {
+    const aliasKeys = identityAliasKeys(identity);
+    const exactAliasMatches = candidates.filter((candidate) => {
+        const candidateAliasKeys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
+        return aliasKeys.some((key) => candidateAliasKeys.includes(key));
+    });
+    if (exactAliasMatches.length === 1) {
+        return exactAliasMatches[0];
+    }
+    if (exactAliasMatches.length > 1) {
+        return null;
+    }
+    const matches = candidates.filter((candidate) => agentIdentityMatches(identity, candidate));
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (!identity.nodeQualifier && !identity.workspaceQualifier && !identity.profile && !identity.harness) {
+        return matches.find((candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId)
+            ?? matches[0]
+            ?? null;
+    }
+    return null;
+}
+export function constructAgentAlias(input) {
+    const alias = normalizeAgentIdentitySegment(trimIdentityPrefix(input.alias));
+    const target = canonicalizeIdentity(input.target);
+    if (!alias || !target) {
+        return null;
+    }
+    return { alias, target };
+}
+export function formatAgentAlias(alias, options = {}) {
+    const prefix = options.includeSigil === false ? "" : "@";
+    return `${prefix}${normalizeAgentIdentitySegment(alias.alias)}`;
+}
+export function resolveAgentAlias(value, aliases) {
+    const aliasKey = normalizeAgentIdentitySegment(trimIdentityPrefix(value));
+    if (!aliasKey) {
+        return null;
+    }
+    const matches = aliases.filter((alias) => normalizeAgentIdentitySegment(alias.alias) === aliasKey);
+    if (matches.length !== 1) {
+        return null;
+    }
+    return constructAgentIdentity(matches[0].target);
+}
+function identitiesDifferOnDimension(left, right, dimension) {
+    return candidateDimensionValue(left, dimension) !== candidateDimensionValue(right, dimension);
+}
+function buildIdentitySubset(candidate, dimensions) {
+    const canonical = candidateCanonicalIdentity(candidate);
+    if (!canonical) {
+        return null;
+    }
+    return constructAgentIdentity({
+        definitionId: canonical.definitionId,
+        ...(dimensions.includes("workspace") && canonical.workspaceQualifier
+            ? { workspaceQualifier: canonical.workspaceQualifier }
+            : {}),
+        ...(dimensions.includes("profile") && canonical.profile ? { profile: canonical.profile } : {}),
+        ...(dimensions.includes("harness") && canonical.harness ? { harness: canonical.harness } : {}),
+        ...(dimensions.includes("node") && canonical.nodeQualifier ? { nodeQualifier: canonical.nodeQualifier } : {}),
+    });
+}
+export function formatMinimalAgentIdentity(candidate, candidates, options = {}) {
+    const canonical = candidateCanonicalIdentity(candidate);
+    if (!canonical) {
+        return options.includeSigil === false ? "" : "@";
+    }
+    const peers = candidates.filter((peer) => {
+        const peerCanonical = candidateCanonicalIdentity(peer);
+        return peerCanonical && peerCanonical.definitionId === canonical.definitionId;
+    });
+    const aliasMatches = explicitCandidateAliases(candidate)
+        .map((alias) => ({ alias, identity: parseAgentIdentity(`@${alias}`) }))
+        .filter((entry) => Boolean(entry.identity))
+        .filter((entry) => resolveAgentIdentity(entry.identity, candidates) === candidate)
+        .sort((left, right) => left.alias.length - right.alias.length || left.alias.localeCompare(right.alias));
+    if (aliasMatches.length > 0) {
+        return formatAgentIdentity({ definitionId: aliasMatches[0].alias }, options);
+    }
+    if (peers.length <= 1) {
+        return formatAgentIdentity({ definitionId: canonical.definitionId }, options);
+    }
+    const orderedDimensions = ["workspace", "profile", "harness", "node"];
+    const selectedDimensions = [];
+    let remainingPeers = peers.filter((peer) => peer !== candidate);
+    for (const dimension of orderedDimensions) {
+        const value = candidateDimensionValue(candidate, dimension);
+        if (!value) {
+            continue;
+        }
+        const splitsRemainingPeers = remainingPeers.some((peer) => identitiesDifferOnDimension(candidate, peer, dimension));
+        if (!splitsRemainingPeers) {
+            continue;
+        }
+        selectedDimensions.push(dimension);
+        remainingPeers = remainingPeers.filter((peer) => (!identitiesDifferOnDimension(candidate, peer, dimension)));
+        const current = buildIdentitySubset(candidate, selectedDimensions);
+        if (current && resolveAgentIdentity(current, candidates)) {
+            return formatAgentIdentity(current, options);
+        }
+    }
+    return formatAgentIdentity(canonical, options);
+}
+export const parseAgentAddress = parseAgentIdentity;
+export const formatAgentAddress = formatAgentIdentity;
+export const constructAgentAddress = constructAgentIdentity;
+export const extractAgentAddresses = extractAgentIdentities;
+export const agentAddressMatches = agentIdentityMatches;
+export const resolveAgentAddress = resolveAgentIdentity;
+export const parseAgentSelector = parseAgentIdentity;
+export const formatAgentSelector = formatAgentIdentity;
+export const extractAgentSelectors = extractAgentIdentities;
+export const agentSelectorMatches = agentIdentityMatches;
+export const resolveAgentSelector = resolveAgentIdentity;

package/dist/agent-selectors.d.ts

@@ -1,27 +1 @@
-import type { ScoutId } from "./common.js";
-export interface AgentSelector {
-    raw: string;
-    label: string;
-    definitionId: ScoutId;
-    nodeQualifier?: string;
-    workspaceQualifier?: string;
-}
-export interface AgentSelectorCandidate {
-    agentId: ScoutId;
-    definitionId?: ScoutId;
-    nodeQualifier?: string;
-    workspaceQualifier?: string;
-    aliases?: string[];
-}
-export declare function normalizeAgentSelectorSegment(value: string): string;
-export declare function parseAgentSelector(value: string): AgentSelector | null;
-export declare function formatAgentSelector(input: {
-    definitionId: ScoutId;
-    nodeQualifier?: string;
-    workspaceQualifier?: string;
-}, options?: {
-    includeSigil?: boolean;
-}): string;
-export declare function extractAgentSelectors(text: string): AgentSelector[];
-export declare function agentSelectorMatches(selector: AgentSelector, candidate: AgentSelectorCandidate): boolean;
-export declare function resolveAgentSelector<T extends AgentSelectorCandidate>(selector: AgentSelector, candidates: T[]): T | null;
+export * from "./agent-address.js";

package/dist/agent-selectors.js

@@ -1,103 +1 @@
-function trimSelectorPrefix(value) {
-    return value
-        .trim()
-        .replace(/^@+/, "")
-        .replace(/[.,!?;:)\]]+$/, "");
-}
-export function normalizeAgentSelectorSegment(value) {
-    return value
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9._/-]+/g, "-")
-        .replace(/[\\/]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-}
-export function parseAgentSelector(value) {
-    const raw = trimSelectorPrefix(value);
-    if (!raw) {
-        return null;
-    }
-    const [definitionAndNode, workspacePart] = raw.split("#", 2);
-    const [definitionPart, nodePart] = definitionAndNode.split("@", 2);
-    const definitionId = normalizeAgentSelectorSegment(definitionPart);
-    const nodeQualifier = nodePart ? normalizeAgentSelectorSegment(nodePart) : undefined;
-    const workspaceQualifier = workspacePart ? normalizeAgentSelectorSegment(workspacePart) : undefined;
-    if (!definitionId) {
-        return null;
-    }
-    return {
-        raw,
-        label: formatAgentSelector({
-            definitionId,
-            nodeQualifier,
-            workspaceQualifier,
-        }),
-        definitionId,
-        ...(nodeQualifier ? { nodeQualifier } : {}),
-        ...(workspaceQualifier ? { workspaceQualifier } : {}),
-    };
-}
-export function formatAgentSelector(input, options = {}) {
-    const definitionId = normalizeAgentSelectorSegment(input.definitionId);
-    if (!definitionId) {
-        return options.includeSigil === false ? "" : "@";
-    }
-    const nodeQualifier = input.nodeQualifier ? normalizeAgentSelectorSegment(input.nodeQualifier) : "";
-    const workspaceQualifier = input.workspaceQualifier ? normalizeAgentSelectorSegment(input.workspaceQualifier) : "";
-    const prefix = options.includeSigil === false ? "" : "@";
-    return [
-        `${prefix}${definitionId}`,
-        nodeQualifier ? `@${nodeQualifier}` : "",
-        workspaceQualifier ? `#${workspaceQualifier}` : "",
-    ].join("");
-}
-export function extractAgentSelectors(text) {
-    const matches = Array.from(text.matchAll(/(^|\s)@([a-z0-9._/-]+(?:@[a-z0-9._/-]+)?(?:#[a-z0-9._/-]+)?)/gi));
-    const selectors = new Map();
-    for (const match of matches) {
-        const candidate = parseAgentSelector(match[2] ?? "");
-        if (!candidate) {
-            continue;
-        }
-        selectors.set(candidate.label, candidate);
-    }
-    return Array.from(selectors.values());
-}
-function candidateAliases(candidate) {
-    const definitionId = normalizeAgentSelectorSegment(candidate.definitionId || candidate.agentId);
-    const nodeQualifier = candidate.nodeQualifier ? normalizeAgentSelectorSegment(candidate.nodeQualifier) : undefined;
-    const workspaceQualifier = candidate.workspaceQualifier ? normalizeAgentSelectorSegment(candidate.workspaceQualifier) : undefined;
-    const aliases = [
-        definitionId,
-        formatAgentSelector({ definitionId, nodeQualifier }),
-        formatAgentSelector({ definitionId, workspaceQualifier }),
-        formatAgentSelector({ definitionId, nodeQualifier, workspaceQualifier }),
-        ...((candidate.aliases ?? []).map((alias) => alias.trim()).filter(Boolean)),
-    ];
-    return Array.from(new Set(aliases.map((alias) => trimSelectorPrefix(alias)).filter(Boolean)));
-}
-export function agentSelectorMatches(selector, candidate) {
-    const definitionId = normalizeAgentSelectorSegment(candidate.definitionId || candidate.agentId);
-    if (selector.definitionId !== definitionId) {
-        return false;
-    }
-    const nodeQualifier = candidate.nodeQualifier ? normalizeAgentSelectorSegment(candidate.nodeQualifier) : undefined;
-    if (selector.nodeQualifier && selector.nodeQualifier !== nodeQualifier) {
-        return candidateAliases(candidate).includes(trimSelectorPrefix(selector.label));
-    }
-    const workspaceQualifier = candidate.workspaceQualifier ? normalizeAgentSelectorSegment(candidate.workspaceQualifier) : undefined;
-    if (selector.workspaceQualifier && selector.workspaceQualifier !== workspaceQualifier) {
-        return candidateAliases(candidate).includes(trimSelectorPrefix(selector.label));
-    }
-    return true;
-}
-export function resolveAgentSelector(selector, candidates) {
-    const matches = candidates.filter((candidate) => agentSelectorMatches(selector, candidate));
-    if (matches.length === 1) {
-        return matches[0];
-    }
-    if (!selector.nodeQualifier && !selector.workspaceQualifier) {
-        return matches.find((candidate) => normalizeAgentSelectorSegment(candidate.agentId) === selector.definitionId) ?? matches[0] ?? null;
-    }
-    return null;
-}
+export * from "./agent-address.js";

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export * from "./common.js";
 export * from "./actors.js";
+export * from "./agent-identity.js";
+export * from "./agent-address.js";
 export * from "./agent-selectors.js";
+export * from "./relay-agent-card.js";
 export * from "./mesh.js";
 export * from "./conversations.js";
 export * from "./collaboration.js";

package/dist/index.js

@@ -1,6 +1,9 @@
 export * from "./common.js";
 export * from "./actors.js";
+export * from "./agent-identity.js";
+export * from "./agent-address.js";
 export * from "./agent-selectors.js";
+export * from "./relay-agent-card.js";
 export * from "./mesh.js";
 export * from "./conversations.js";
 export * from "./collaboration.js";

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

@@ -0,0 +1,38 @@
+import type { AgentEndpoint, AgentHarness } from "./actors.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+export interface RelayReturnAddress {
+    actorId: ScoutId;
+    handle: string;
+    displayName?: string;
+    selector?: string;
+    defaultSelector?: string;
+    conversationId?: ScoutId;
+    replyToMessageId?: ScoutId;
+    nodeId?: ScoutId;
+    projectRoot?: string;
+    sessionId?: string;
+    metadata?: MetadataMap;
+}
+export interface RelayAgentCard {
+    id: ScoutId;
+    agentId: ScoutId;
+    definitionId: ScoutId;
+    displayName: string;
+    handle: string;
+    selector?: string;
+    defaultSelector?: string;
+    projectName?: string;
+    projectRoot: string;
+    currentDirectory: string;
+    harness: AgentHarness;
+    transport: AgentEndpoint["transport"];
+    sessionId?: string;
+    branch?: string;
+    createdAt: number;
+    createdById?: ScoutId;
+    brokerRegistered: boolean;
+    inboxConversationId?: ScoutId;
+    returnAddress: RelayReturnAddress;
+    metadata?: MetadataMap;
+}
+export declare function buildRelayReturnAddress(input: RelayReturnAddress): RelayReturnAddress;

package/dist/relay-agent-card.js

@@ -0,0 +1,34 @@
+export function buildRelayReturnAddress(input) {
+    const next = {
+        actorId: input.actorId,
+        handle: input.handle.trim(),
+    };
+    if (input.displayName?.trim()) {
+        next.displayName = input.displayName.trim();
+    }
+    if (input.selector?.trim()) {
+        next.selector = input.selector.trim();
+    }
+    if (input.defaultSelector?.trim()) {
+        next.defaultSelector = input.defaultSelector.trim();
+    }
+    if (input.conversationId?.trim()) {
+        next.conversationId = input.conversationId.trim();
+    }
+    if (input.replyToMessageId?.trim()) {
+        next.replyToMessageId = input.replyToMessageId.trim();
+    }
+    if (input.nodeId?.trim()) {
+        next.nodeId = input.nodeId.trim();
+    }
+    if (input.projectRoot?.trim()) {
+        next.projectRoot = input.projectRoot.trim();
+    }
+    if (input.sessionId?.trim()) {
+        next.sessionId = input.sessionId.trim();
+    }
+    if (input.metadata && Object.keys(input.metadata).length > 0) {
+        next.metadata = input.metadata;
+    }
+    return next;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscout/protocol",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Typed protocol for the OpenScout local control plane",
   "type": "module",
   "exports": {
@@ -17,7 +17,8 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
-    "check": "tsc --noEmit -p tsconfig.json"
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test src/*.test.ts"
   },
   "publishConfig": {
     "access": "public"