letagents 0.12.8 → 0.12.10

package/dist/mcp/sse-client.js

@@ -1,5 +1,4 @@
 import { encodeRoomIdPath } from "./room-id.js";
-import { buildRoomAgentPrompt, normalizeAgentPromptKind } from "../shared/room-agent-prompts.js";
 export class SseClient {
     apiUrl;
     getAccessToken;
@@ -54,7 +53,7 @@ export class SseClient {
     }
     async consumeStream(target, signal, onMessage) {
         try {
-            await this.openStream(this.withIncludePromptOnly(`${this.apiUrl}/rooms/${encodeRoomIdPath(target.roomId)}/messages/stream`), signal, onMessage);
+            await this.openStream(this.withIncludePromptOnly(this.withAgentIdentityQuery(`${this.apiUrl}/rooms/${encodeRoomIdPath(target.roomId)}/messages/stream`, target)), signal, onMessage);
             return;
         }
         catch (error) {
@@ -62,11 +61,25 @@ export class SseClient {
                 throw error;
             }
         }
-        await this.openStream(this.withIncludePromptOnly(`${this.apiUrl}/projects/${encodeURIComponent(target.projectId)}/messages/stream`), signal, onMessage);
+        await this.openStream(this.withIncludePromptOnly(this.withAgentIdentityQuery(`${this.apiUrl}/projects/${encodeURIComponent(target.projectId)}/messages/stream`, target)), signal, onMessage);
     }
     withIncludePromptOnly(url) {
         return `${url}${url.includes("?") ? "&" : "?"}include_prompt_only=1`;
     }
+    withAgentIdentityQuery(url, target) {
+        const actorLabel = target.agentIdentity?.actorLabel?.trim();
+        const actorKey = target.agentIdentity?.actorKey?.trim();
+        if (!actorLabel || !actorKey) {
+            return url;
+        }
+        const params = new URLSearchParams();
+        params.set("actor_label", actorLabel);
+        params.set("actor_key", actorKey);
+        if (target.agentIdentity?.actorInstanceId?.trim()) {
+            params.set("actor_instance_id", target.agentIdentity.actorInstanceId.trim());
+        }
+        return `${url}${url.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
     async openStream(url, signal, onMessage) {
         const response = await fetch(url, {
             headers: this.getHeaders(),
@@ -109,19 +122,12 @@ export class SseClient {
         if (dataLines.length === 0) {
             return;
         }
-        onMessage(this.enrichPromptMetadata(JSON.parse(dataLines.join("\n"))));
-    }
-    enrichPromptMetadata(message) {
-        const kind = normalizeAgentPromptKind(message.agent_prompt_kind);
-        if (!kind) {
-            return message;
-        }
-        return {
-            ...message,
-            visible_text: message.text,
-            agent_prompt: buildRoomAgentPrompt(kind),
-            prompt_injected: kind === "inline",
-        };
+        // No prompt enrichment here: the only SSE subscriber (room-state.ts) discards
+        // the message body, and expanding the room-agent prompt on this background
+        // path would consume the once-per-session full-prompt delivery before the
+        // agent ever sees it. Prompt expansion happens only on visible tool
+        // responses (runtime/messages.ts).
+        onMessage(JSON.parse(dataLines.join("\n")));
     }
     isMissingRouteError(error) {
         return (error instanceof Error &&

package/dist/shared/activation-routing.js

@@ -0,0 +1,263 @@
+const NON_AGENT_AT_HANDLES = new Set([
+    "charset",
+    "container",
+    "counter-style",
+    "font-face",
+    "font-feature-values",
+    "font-palette-values",
+    "import",
+    "keyframes",
+    "layer",
+    "media",
+    "namespace",
+    "page",
+    "package",
+    "property",
+    "scope",
+    "starting-style",
+    "supports",
+    "types",
+    "viewport",
+]);
+const TASK_OWNER_FOLLOW_UP_PATTERNS = [
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:try again|retry|rerun|re-run|continue|proceed|go ahead|carry on)\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:open|create|make|raise)\s+(?:a\s+)?pr\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:push|merge|ship|fix|test|run|update)\s+(?:it|that|this|again|tests?|the\s+tests?|ci)\b/,
+    /\b(?:try again|open\s+(?:a\s+)?pr|create\s+(?:a\s+)?pr|make\s+(?:a\s+)?pr|push it|merge it|update it)\b/,
+];
+export function attachAgentMessageActivation(message, identity, context = {}) {
+    return {
+        ...message,
+        activation: {
+            for_current_agent: decideAgentMessageActivation(message, identity, context),
+        },
+    };
+}
+export function attachAgentMessageActivations(messages, identity, context = {}) {
+    if (!identity || identity.session_kind !== "worker") {
+        return [...messages];
+    }
+    return messages.map((message) => attachAgentMessageActivation(message, identity, context));
+}
+export function decideAgentMessageActivation(message, identity, context = {}) {
+    if (senderMatchesIdentity(message.sender, identity)) {
+        return decision("silent", "self_message");
+    }
+    const mentions = extractMentionHandles(message.text);
+    if (mentions.some(isBroadcastHandle)) {
+        return decision("activate", "broadcast");
+    }
+    if (mentions.some((mention) => identityAliases(identity).has(normalizeHandle(mention)))) {
+        return decision("activate", "explicit_mention");
+    }
+    if (hasBroadcastAddress(message.text)) {
+        return decision("activate", "broadcast");
+    }
+    if (mentions.some(isLikelyAgentMentionHandle)) {
+        return decision("silent", "explicit_other_mention");
+    }
+    if (senderMatchesIdentity(message.reply_to?.sender, identity)) {
+        return decision("activate", "reply_target");
+    }
+    if (isAgentReplyTarget(message.reply_to) && !isThreadReply(message)) {
+        return decision("silent", "other_reply_target");
+    }
+    if (isThreadReply(message) && threadParticipantsIncludeIdentity(message, identity)) {
+        return decision("activate", "thread_participant");
+    }
+    const taskOwnerDecision = decideTaskOwnerActivation(message, identity, context);
+    if (taskOwnerDecision) {
+        return taskOwnerDecision;
+    }
+    return decision("unclear", "unaddressed");
+}
+function decision(decisionValue, reason) {
+    return {
+        decision: decisionValue,
+        reason,
+        addressed: decisionValue === "activate",
+    };
+}
+function isThreadReply(message) {
+    const ownId = normalizedString(message.id);
+    const rootId = normalizedString(message.thread_root_id) || normalizedString(message.thread?.root_message_id);
+    return Boolean(ownId && rootId && ownId !== rootId);
+}
+function isAgentReplyTarget(replyTo) {
+    return normalizeSender(replyTo?.source) === "agent";
+}
+function threadParticipantsIncludeIdentity(message, identity) {
+    const senders = [
+        message.reply_to?.sender,
+        message.thread?.latest_reply?.sender,
+        ...(message.thread?.participants ?? []).map((participant) => participant.sender),
+    ];
+    return senders.some((sender) => senderMatchesIdentity(sender, identity));
+}
+function decideTaskOwnerActivation(message, identity, context) {
+    if (!isTaskOwnerFollowUp(message.text)) {
+        return null;
+    }
+    const owners = uniqueActiveWorkOwners(context.activeTaskLeases ?? []);
+    if (owners.length !== 1) {
+        return null;
+    }
+    const owner = owners[0];
+    if (senderMatchesLeaseOwner(message.sender, owner)) {
+        return null;
+    }
+    if (leaseOwnerMatchesIdentity(owner, identity)) {
+        return decision("activate", "task_owner");
+    }
+    if (identityOverlapsLeaseOwner(identity, owner)) {
+        return null;
+    }
+    return decision("silent", "task_owner");
+}
+function uniqueActiveWorkOwners(leases) {
+    const ownersByKey = new Map();
+    for (const lease of leases) {
+        if (lease.kind !== "work" || lease.status !== "active")
+            continue;
+        const key = leaseOwnerKey(lease);
+        if (!key)
+            continue;
+        ownersByKey.set(key, lease);
+    }
+    return [...ownersByKey.values()];
+}
+function leaseOwnerKey(lease) {
+    const sessionId = normalizedString(lease.agent_session_id);
+    if (sessionId)
+        return `session:${sessionId}`;
+    const instanceId = normalizedString(lease.agent_instance_id);
+    const agentKey = normalizeSender(lease.agent_key);
+    if (instanceId)
+        return `instance:${agentKey}:${instanceId}`;
+    if (agentKey)
+        return `agent:${agentKey}`;
+    const actorLabel = normalizeSender(lease.actor_label);
+    return actorLabel ? `label:${actorLabel}` : null;
+}
+function leaseOwnerMatchesIdentity(lease, identity) {
+    const leaseSessionId = normalizedString(lease.agent_session_id);
+    if (leaseSessionId) {
+        return leaseSessionId === normalizedString(identity.agent_session_id);
+    }
+    const leaseInstanceId = normalizedString(lease.agent_instance_id);
+    if (leaseInstanceId) {
+        return (leaseInstanceId === normalizedString(identity.agent_instance_id) &&
+            normalizeSender(lease.agent_key) === normalizeSender(identity.agent_key));
+    }
+    const leaseAgentKey = normalizeSender(lease.agent_key);
+    if (leaseAgentKey) {
+        return leaseAgentKey === normalizeSender(identity.agent_key);
+    }
+    return senderMatchesIdentity(lease.actor_label, identity);
+}
+function senderMatchesLeaseOwner(sender, lease) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    return leaseOwnerAliases(lease).has(normalizedSender);
+}
+function identityOverlapsLeaseOwner(identity, lease) {
+    const identityAliasesForOwner = aliasesForValues([
+        identity.actor_label,
+        identity.display_name,
+        identity.agent_key,
+        identity.agent_instance_id,
+        identity.agent_session_id,
+    ]);
+    for (const ownerAlias of leaseOwnerAliases(lease)) {
+        if (identityAliasesForOwner.has(ownerAlias)) {
+            return true;
+        }
+    }
+    return false;
+}
+function leaseOwnerAliases(lease) {
+    return aliasesForValues([
+        lease.actor_label,
+        ...String(lease.actor_label || "").split("|"),
+        lease.agent_key,
+        lease.agent_instance_id,
+        lease.agent_session_id,
+    ]);
+}
+function aliasesForValues(values) {
+    const aliases = new Set();
+    for (const value of values) {
+        const senderAlias = normalizeSender(value);
+        if (senderAlias)
+            aliases.add(senderAlias);
+        const handleAlias = normalizeHandle(value);
+        if (handleAlias)
+            aliases.add(handleAlias);
+    }
+    return aliases;
+}
+function senderMatchesIdentity(sender, identity) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    const aliases = identityAliases(identity);
+    if (aliases.has(normalizedSender))
+        return true;
+    return String(sender || "")
+        .split("|")
+        .some((part) => aliases.has(normalizeSender(part)));
+}
+function identityAliases(identity) {
+    const aliases = new Set();
+    const values = [
+        identity.actor_label,
+        identity.display_name,
+        identity.agent_key,
+        identity.agent_key.split("/").pop(),
+    ];
+    for (const alias of aliasesForValues(values))
+        aliases.add(alias);
+    return aliases;
+}
+function extractMentionHandles(text) {
+    const raw = typeof text === "string" ? text : "";
+    const mentions = [];
+    for (const match of raw.matchAll(/(^|[\s([{:;,])@([A-Za-z0-9][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9][A-Za-z0-9_.-]*)?)/g)) {
+        mentions.push(match[2]);
+    }
+    return mentions;
+}
+function isBroadcastHandle(handle) {
+    const normalized = normalizeHandle(handle);
+    return normalized === "agents" || normalized === "everyone" || normalized === "room";
+}
+function isLikelyAgentMentionHandle(handle) {
+    const raw = normalizedString(handle);
+    if (!raw)
+        return false;
+    const normalized = raw.toLowerCase();
+    if (normalized.includes("/") && normalized === raw)
+        return false;
+    const firstSegment = normalized.split("/", 1)[0].replace(/_/g, "-");
+    return !NON_AGENT_AT_HANDLES.has(firstSegment);
+}
+function hasBroadcastAddress(text) {
+    const raw = typeof text === "string" ? text.toLowerCase() : "";
+    return /\b(everyone|all agents|you guys|both of you|any agent|whoever owns this)\b/.test(raw);
+}
+function isTaskOwnerFollowUp(text) {
+    const raw = typeof text === "string" ? text.trim().toLowerCase() : "";
+    if (!raw)
+        return false;
+    return TASK_OWNER_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(raw));
+}
+function normalizedString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizeSender(value) {
+    return normalizedString(value).toLowerCase().replace(/\s+/g, " ");
+}
+function normalizeHandle(value) {
+    return normalizedString(value).toLowerCase().replace(/[^a-z0-9_.-]+/g, "");
+}

package/dist/shared/agent-identity.js

@@ -35,24 +35,40 @@ export function formatOwnerAttribution(ownerLabel) {
     return /s$/i.test(trimmed) ? `${trimmed}' agent` : `${trimmed}'s agent`;
 }
 export function inferAgentIdeLabel(value) {
-    const normalized = normalizeWhitespace(String(value ?? "")).toLowerCase();
+    const raw = normalizeWhitespace(String(value ?? ""));
+    const normalized = raw.toLowerCase();
     if (!normalized) {
         return null;
     }
-    if (normalized === "codex" || normalized.startsWith("codex-")) {
+    if (matchesRuntimePrefix(raw, "codex")) {
         return "Codex";
     }
-    if (normalized === "antigravity" || normalized.startsWith("antigravity-")) {
+    if (matchesRuntimePrefix(raw, "antigravity")) {
         return "Antigravity";
     }
-    if (normalized === "claude" || normalized.startsWith("claude-")) {
+    if (matchesRuntimePrefix(raw, "claude")) {
         return "Claude";
     }
-    if (normalized === "orchestrator" || normalized.startsWith("orchestrator-")) {
+    if (matchesRuntimePrefix(raw, "orchestrator")) {
         return "Orchestrator";
     }
     return null;
 }
+function matchesRuntimePrefix(value, prefix) {
+    const normalized = value.toLowerCase();
+    if (normalized === prefix || normalized.startsWith(`${prefix}-`)) {
+        return true;
+    }
+    const compact = value.replace(/[^a-zA-Z0-9]+/g, "");
+    if (compact.toLowerCase() === prefix) {
+        return true;
+    }
+    if (!compact.toLowerCase().startsWith(prefix)) {
+        return false;
+    }
+    const next = compact[prefix.length];
+    return Boolean(next && /[A-Z0-9]/.test(next));
+}
 export function buildAgentActorLabel(input) {
     const displayName = normalizeWhitespace(input.display_name) || "Agent";
     const ownerAttribution = formatOwnerAttribution(input.owner_label);

package/dist/shared/agent-presence.js

@@ -9,6 +9,20 @@ export const AGENT_PRESENCE_FRESHNESS = [
     "stale",
 ];
 export const ACTIVE_AGENT_PRESENCE_WINDOW_MS = 90_000;
+export const ACTIVE_AGENT_DELIVERY_WINDOW_MS = ACTIVE_AGENT_PRESENCE_WINDOW_MS;
+export const ROOM_AGENT_DELIVERY_HEARTBEAT_INTERVAL_MS = 30_000;
+export const ROOM_AGENT_RECONNECT_GRACE_MS = 10_000;
+export const ROOM_AGENT_DELIVERY_TRANSPORTS = [
+    "long_poll",
+    "sse",
+];
+export const ROOM_AGENT_SESSION_KINDS = [
+    "controller",
+    "worker",
+];
+export function normalizeRoomAgentSessionKind(value) {
+    return String(value || "").trim().toLowerCase() === "worker" ? "worker" : "controller";
+}
 export function normalizeAgentPresenceStatus(value) {
     const normalized = String(value || "").trim().toLowerCase();
     return AGENT_PRESENCE_STATUSES.includes(normalized)
@@ -24,3 +38,13 @@ export function getAgentPresenceFreshness(lastHeartbeatAt, now = Date.now()) {
         ? "active"
         : "stale";
 }
+export function getAgentPresenceFreshnessFromReachability(isReachable) {
+    return isReachable ? "active" : "stale";
+}
+export function isAgentDeliverySessionReachable(input, now = Date.now()) {
+    if (input.activeConnectionCount > 0 && getAgentPresenceFreshness(input.updatedAt ?? "", now) === "active") {
+        return true;
+    }
+    const graceExpiresAt = new Date(input.reconnectGraceExpiresAt ?? "").getTime();
+    return Number.isFinite(graceExpiresAt) && graceExpiresAt >= now;
+}

package/dist/shared/handoff.js

@@ -0,0 +1,145 @@
+export const HANDOFF_EXECUTION_MODES = [
+    "hosted_isolated",
+    "supplier_local",
+];
+export const HANDOFF_SUPPORTED_EXECUTION_MODES = [
+    "hosted_isolated",
+];
+export const HANDOFF_OUTPUT_TYPES = [
+    "research_note",
+    "comment",
+    "draft_pr",
+];
+export const HANDOFF_PERMISSION_PROFILES = [
+    "research_readonly",
+    "comment_review",
+    "draft_pr_write",
+];
+export const HANDOFF_SESSION_STATUSES = [
+    "requested",
+    "approved",
+    "running",
+    "completed",
+    "failed",
+    "revoked",
+    "expired",
+    "cancelled",
+];
+export const HANDOFF_GRANT_TYPES = [
+    "repo_read",
+    "branch_write",
+    "pr_comment",
+    "secret",
+];
+export const HANDOFF_GRANT_STATUSES = [
+    "active",
+    "revoked",
+    "expired",
+];
+export const HANDOFF_OUTPUT_TO_PERMISSION_PROFILE = {
+    research_note: "research_readonly",
+    comment: "comment_review",
+    draft_pr: "draft_pr_write",
+};
+export const HANDOFF_OUTPUT_TO_GRANT_TYPES = {
+    research_note: ["repo_read"],
+    comment: ["repo_read", "pr_comment"],
+    draft_pr: ["repo_read", "branch_write"],
+};
+function normalizeEnumValue(value, allowed) {
+    const normalized = String(value || "").trim().toLowerCase();
+    return allowed.includes(normalized) ? normalized : null;
+}
+export function normalizeHandoffExecutionMode(value) {
+    return normalizeEnumValue(value, HANDOFF_EXECUTION_MODES);
+}
+export function normalizeHandoffOutputType(value) {
+    return normalizeEnumValue(value, HANDOFF_OUTPUT_TYPES);
+}
+export function normalizeHandoffPermissionProfile(value) {
+    return normalizeEnumValue(value, HANDOFF_PERMISSION_PROFILES);
+}
+export function normalizeHandoffSessionStatus(value) {
+    return normalizeEnumValue(value, HANDOFF_SESSION_STATUSES);
+}
+export function normalizeHandoffGrantType(value) {
+    return normalizeEnumValue(value, HANDOFF_GRANT_TYPES);
+}
+export function normalizeHandoffGrantStatus(value) {
+    return normalizeEnumValue(value, HANDOFF_GRANT_STATUSES);
+}
+export function getDefaultHandoffPermissionProfile(outputType) {
+    return HANDOFF_OUTPUT_TO_PERMISSION_PROFILE[outputType];
+}
+export function getDefaultHandoffGrantTypes(outputType) {
+    return HANDOFF_OUTPUT_TO_GRANT_TYPES[outputType];
+}
+export function isSupportedHandoffExecutionMode(mode) {
+    return HANDOFF_SUPPORTED_EXECUTION_MODES.includes(mode);
+}
+/** Default grant TTLs for v1 (strict boundaries); callers may shorten, not widen, without re-approval. */
+export const HANDOFF_DEFAULT_GRANT_TTL_MS = {
+    research_note: 4 * 60 * 60 * 1000,
+    comment: 8 * 60 * 60 * 1000,
+    draft_pr: 48 * 60 * 60 * 1000,
+};
+export function resolveHandoffPermissionProfile(outputType, permissionProfile) {
+    return permissionProfile ?? getDefaultHandoffPermissionProfile(outputType);
+}
+export function permissionProfileMatchesOutput(outputType, permissionProfile) {
+    return HANDOFF_OUTPUT_TO_PERMISSION_PROFILE[outputType] === permissionProfile;
+}
+export function buildHandoffCapabilityManifest(input) {
+    const grantTypes = getDefaultHandoffGrantTypes(input.outputType);
+    const grants = grantTypes.map((grant_type) => ({
+        grant_type,
+        scope: input.repoScope.trim(),
+        scoped_branch: grant_type === "branch_write" ? input.targetBranch.trim() : null,
+    }));
+    return {
+        policy_version: 1,
+        execution_mode: input.executionMode,
+        output_type: input.outputType,
+        permission_profile: input.permissionProfile,
+        repo_instructions_trusted: false,
+        recursive_handoff: "deny",
+        grants,
+    };
+}
+/**
+ * Core v1 policy: sovereign platform manifest, single contracted execution lane,
+ * output-bound permission profiles, no recursive handoff.
+ */
+export function evaluateHandoffPolicy(input) {
+    const executionMode = input.executionMode ?? "hosted_isolated";
+    if (!isSupportedHandoffExecutionMode(executionMode)) {
+        return {
+            ok: false,
+            code: "unsupported_execution_mode",
+            message: `Execution mode ${executionMode} is not supported for v1 handoffs.`,
+        };
+    }
+    if (input.parentSessionId) {
+        return {
+            ok: false,
+            code: "recursive_handoff_forbidden",
+            message: "Nested handoff sessions are blocked in v1; start a new approved handoff instead.",
+        };
+    }
+    const permissionProfile = resolveHandoffPermissionProfile(input.outputType, input.permissionProfile);
+    if (!permissionProfileMatchesOutput(input.outputType, permissionProfile)) {
+        return {
+            ok: false,
+            code: "permission_profile_mismatch",
+            message: `Permission profile ${permissionProfile} does not match output type ${input.outputType}.`,
+        };
+    }
+    const manifest = buildHandoffCapabilityManifest({
+        outputType: input.outputType,
+        permissionProfile,
+        executionMode,
+        repoScope: input.repoScope,
+        targetBranch: input.targetBranch,
+    });
+    return { ok: true, permissionProfile, executionMode, manifest };
+}