@openscout/protocol 0.2.109 → 0.2.110

package/src/agent-notifications.ts

@@ -0,0 +1,241 @@
+/**
+ * Agent notifications: what an agent's notification IS, so the phone can pick
+ * the view that fits it.
+ *
+ * Every notification declares a `view` and the typed fields that view needs.
+ * The same record renders in three places: the lock screen (text only, via
+ * {@link collapseAgentNotification}), the long-press view, and the app's
+ * Notifications row. A client that doesn't know a `view` renders `text`.
+ *
+ * Everything that wants the operator is a question of some kind; the prefix
+ * says WHEN it was asked:
+ *   - `turn.*` is mid-turn: the turn is paused until the operator answers.
+ *   - `ask` is outside a turn: the agent finished and reached out on its own.
+ * Only declared things become notifications. Inferred attention never does.
+ *
+ * The record travels sealed (see the runtime's mobile-push sealing): the relay
+ * that delivers the push never reads any of it.
+ */
+
+export const AGENT_NOTIFICATION_VERSION = 1 as const;
+
+export type AgentNotificationRisk = "low" | "medium" | "high";
+
+export type AgentNotificationFileChange = {
+  path: string;
+  added: number;
+  removed: number;
+};
+
+export type AgentNotificationArtifact = {
+  kind: "pr" | "build" | "file" | "link";
+  label: string;
+  meta?: string;
+  url?: string;
+};
+
+export type AgentNotificationView =
+  | { view: "turn.approve.command"; command: string; cwd?: string; risk: AgentNotificationRisk; why?: string }
+  | { view: "turn.approve.edit"; summary?: string; files: AgentNotificationFileChange[]; risk: AgentNotificationRisk }
+  | { view: "turn.approve.tool"; tool: string; summary?: string; risk: AgentNotificationRisk }
+  | { view: "turn.question.choice"; question: string; context?: string; options: string[]; multiSelect?: boolean }
+  | { view: "turn.question.open"; question: string; context?: string }
+  | { view: "turn.failed"; error: string; excerpt?: string[]; elapsed?: string }
+  | { view: "work.done"; summary: string; artifacts?: AgentNotificationArtifact[] }
+  | { view: "ask"; note: string; options?: string[] }
+  | { view: "text"; title: string; body?: string };
+
+export type AgentNotificationViewName = AgentNotificationView["view"];
+
+export type AgentNotificationAction =
+  | "approve"
+  | "deny"
+  | "reply"
+  | "open_chat"
+  | "open_link";
+
+export type AgentNotification = AgentNotificationView & {
+  v: typeof AGENT_NOTIFICATION_VERSION;
+  /** Stable id of the thing that wants attention (inbox item, message). */
+  itemId: string;
+  /** The agent, as the operator knows it. */
+  sender: { name: string; agentId?: string };
+  project?: string;
+  /** The Mac it happened on. */
+  host?: string;
+  /** Declared and still open: Time Sensitive on the lock screen, Priority in the app. */
+  urgent: boolean;
+  createdAt: number;
+  /** Routing back into the app. */
+  route?: {
+    sessionId?: string;
+    turnId?: string;
+    blockId?: string;
+    conversationId?: string;
+    messageId?: string;
+  };
+};
+
+export type AgentNotificationCollapse = {
+  /** Lock-screen title: the agent. */
+  title: string;
+  /** Lock-screen subtitle: project · host. */
+  subtitle: string;
+  /** Lock-screen body: headline, then the most useful line that fits as text. */
+  body: string;
+  /** Row headline in the app. Same words as line 1 of the body. */
+  headline: string;
+  /** iOS notification category, which carries the actions. */
+  category: string;
+  /** One thread per agent, so stacks group by who sent them. */
+  threadId: string;
+};
+
+/**
+ * What travels sealed in a push: the record plus its lock-screen text,
+ * computed once here so the phone's extension applies it verbatim and no
+ * client re-derives the words.
+ */
+export type SealedAgentNotification = AgentNotification & {
+  lockScreen: Pick<AgentNotificationCollapse, "title" | "subtitle" | "body" | "category" | "threadId">;
+};
+
+export function sealedAgentNotification(n: AgentNotification): SealedAgentNotification {
+  const { title, subtitle, body, category, threadId } = collapseAgentNotification(n);
+  return { ...n, lockScreen: { title, subtitle, body, category, threadId } };
+}
+
+function riskLabel(risk: AgentNotificationRisk): string {
+  return risk === "high" ? "High risk" : risk === "medium" ? "Medium risk" : "Low risk";
+}
+
+function plural(count: number, one: string, many: string): string {
+  return `${count} ${count === 1 ? one : many}`;
+}
+
+export function agentNotificationHeadline(n: AgentNotification): string {
+  switch (n.view) {
+    case "turn.approve.command": return "Wants to run a command";
+    case "turn.approve.edit": return `Wants to edit ${plural(n.files.length, "file", "files")}`;
+    case "turn.approve.tool": return `Wants to use ${n.tool}`;
+    case "turn.question.choice": return n.question;
+    case "turn.question.open": return n.question;
+    case "turn.failed": return `Turn failed: ${n.error}`;
+    case "work.done": return `Done: ${n.summary}`;
+    case "ask": return "Asked for you";
+    case "text": return n.title;
+  }
+}
+
+function detailLine(n: AgentNotification): string {
+  switch (n.view) {
+    case "turn.approve.command": return `${n.command} · ${riskLabel(n.risk)}`;
+    case "turn.approve.edit": {
+      const added = n.files.reduce((sum, f) => sum + f.added, 0);
+      const removed = n.files.reduce((sum, f) => sum + f.removed, 0);
+      const counts = `+${added} −${removed}`;
+      return n.summary ? `${counts} · ${n.summary}` : `${counts} · ${n.files.map((f) => f.path).join(", ")}`;
+    }
+    case "turn.approve.tool": return n.summary ? `${n.summary} · ${riskLabel(n.risk)}` : riskLabel(n.risk);
+    case "turn.question.choice": return n.options.join(" · ");
+    case "turn.question.open": return n.context ?? "";
+    case "turn.failed": return n.elapsed ? `After ${n.elapsed}. The session is still open.` : "The session is still open.";
+    case "work.done": return (n.artifacts ?? []).map((a) => a.meta ? `${a.label} ${a.meta}` : a.label).join(" · ");
+    case "ask": return n.note;
+    case "text": return n.body ?? "";
+  }
+}
+
+/** The actions a view offers, in order. The first is the primary one. */
+export function agentNotificationActions(n: AgentNotification): AgentNotificationAction[] {
+  switch (n.view) {
+    case "turn.approve.command":
+    case "turn.approve.edit":
+    case "turn.approve.tool":
+      return ["approve", "deny"];
+    case "turn.question.choice":
+    case "turn.question.open":
+    case "ask":
+      return ["reply"];
+    case "turn.failed":
+      return ["open_chat"];
+    case "work.done":
+      return (n.artifacts ?? []).some((a) => a.url) ? ["open_link", "open_chat"] : ["open_chat"];
+    case "text":
+      return [];
+  }
+}
+
+/** iOS category ids. Registered by the app with their actions. */
+export function agentNotificationCategory(n: AgentNotification): string {
+  switch (n.view) {
+    case "turn.approve.command":
+    case "turn.approve.edit":
+    case "turn.approve.tool":
+      return "scout.approval";
+    case "turn.question.choice":
+    case "turn.question.open":
+    case "ask":
+      return "scout.question";
+    case "turn.failed":
+    case "work.done":
+      return "scout.open";
+    case "text":
+      return "scout.text";
+  }
+}
+
+export function collapseAgentNotification(n: AgentNotification): AgentNotificationCollapse {
+  const headline = agentNotificationHeadline(n);
+  const line2 = detailLine(n).trim();
+  const where = [n.project, n.host].filter((part): part is string => Boolean(part && part.trim())).join(" · ");
+  return {
+    title: n.sender.name,
+    subtitle: where,
+    body: line2 && line2 !== headline ? `${headline}\n${line2}` : headline,
+    headline,
+    category: agentNotificationCategory(n),
+    threadId: `scout.agent.${n.sender.agentId ?? n.sender.name}`,
+  };
+}
+
+const MAX_TEXT = 600;
+
+function clip(value: string, max = MAX_TEXT): string {
+  const trimmed = value.trim();
+  return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max - 1)}…`;
+}
+
+/**
+ * Bound every free-text field so a sealed record fits inside one APNs push
+ * (4 KB, shared with the alert text). Lists are capped too; the app loads the
+ * full item when it opens.
+ */
+export function clampAgentNotification(n: AgentNotification): AgentNotification {
+  const base = {
+    ...n,
+    sender: { ...n.sender, name: clip(n.sender.name, 80) },
+    ...(n.project ? { project: clip(n.project, 80) } : {}),
+    ...(n.host ? { host: clip(n.host, 80) } : {}),
+  };
+  switch (base.view) {
+    case "turn.approve.command":
+      return { ...base, command: clip(base.command, 400), ...(base.why ? { why: clip(base.why, 300) } : {}) };
+    case "turn.approve.edit":
+      return { ...base, files: base.files.slice(0, 8).map((f) => ({ ...f, path: clip(f.path, 160) })), ...(base.summary ? { summary: clip(base.summary, 300) } : {}) };
+    case "turn.approve.tool":
+      return { ...base, tool: clip(base.tool, 80), ...(base.summary ? { summary: clip(base.summary, 300) } : {}) };
+    case "turn.question.choice":
+      return { ...base, question: clip(base.question, 400), options: base.options.slice(0, 6).map((o) => clip(o, 60)), ...(base.context ? { context: clip(base.context, 300) } : {}) };
+    case "turn.question.open":
+      return { ...base, question: clip(base.question, 400), ...(base.context ? { context: clip(base.context, 300) } : {}) };
+    case "turn.failed":
+      return { ...base, error: clip(base.error, 200), ...(base.excerpt ? { excerpt: base.excerpt.slice(-4).map((l) => clip(l, 120)) } : {}) };
+    case "work.done":
+      return { ...base, summary: clip(base.summary, 300), ...(base.artifacts ? { artifacts: base.artifacts.slice(0, 4) } : {}) };
+    case "ask":
+      return { ...base, note: clip(base.note, 500), ...(base.options ? { options: base.options.slice(0, 6).map((o) => clip(o, 60)) } : {}) };
+    case "text":
+      return { ...base, title: clip(base.title, 120), ...(base.body ? { body: clip(base.body, 400) } : {}) };
+  }
+}

package/src/channel-invites.ts

@@ -126,7 +126,8 @@ export type ChannelInviteRejectionReason =
   | "exhausted"
   | "scope_mismatch"
   | "channel_mismatch"
-  | "missing_identity";
+  | "missing_identity"
+  | "membership_removed";
 
 export interface ChannelInviteRejection {
   reason: ChannelInviteRejectionReason;
@@ -305,6 +306,8 @@ export function findChannelInviteByTokenHash(
  * understand the offer, and nothing that could be replayed into membership.
  */
 export interface ChannelInvitePublicView {
+  /** Explicit where the issuer supports single-use human invitations. */
+  kind?: "teammate" | "agent" | "api";
   id: ScoutId;
   channelId: ScoutId;
   /** Public authorship, used to show who may revoke this invitation. */

package/src/channel-membership.ts

@@ -0,0 +1,22 @@
+import type { MetadataMap } from "./common.js";
+
+/** Broker-written removals preserve history while invalidating older join links. */
+export const CHANNEL_MEMBER_REMOVALS_KEY = "channelMemberRemovals";
+
+export interface ChannelMemberRemoval {
+  removedAt: number;
+  removedByActorId: string;
+  blockedInviteIds: string[];
+}
+
+export function readChannelMemberRemoval(metadata: MetadataMap | undefined, actorId: string): ChannelMemberRemoval | null {
+  const records = metadata?.[CHANNEL_MEMBER_REMOVALS_KEY];
+  if (!records || typeof records !== "object" || Array.isArray(records) || !Object.hasOwn(records, actorId)) return null;
+  const value = (records as Record<string, unknown>)[actorId];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const entry = value as Record<string, unknown>;
+  if (typeof entry.removedAt !== "number" || !Number.isFinite(entry.removedAt)
+    || typeof entry.removedByActorId !== "string" || !Array.isArray(entry.blockedInviteIds)
+    || !entry.blockedInviteIds.every(id => typeof id === "string")) return null;
+  return { removedAt: entry.removedAt, removedByActorId: entry.removedByActorId, blockedInviteIds: entry.blockedInviteIds as string[] };
+}

package/src/chat-mentions.ts

@@ -0,0 +1,11 @@
+/** Explicit attention recipients. Text is payload and is never parsed as routing. */
+export const MAX_CHAT_MENTIONS = 20;
+
+export function parseChatMentionActorIds(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_CHAT_MENTIONS
+    || value.some(id => typeof id !== "string" || !id.trim() || id.length > 256)) {
+    throw new Error("Choose at most 20 valid mention recipients.");
+  }
+  return [...new Set(value.map(id => (id as string).trim()))].sort();
+}

package/src/chat-message-corrections.ts

@@ -0,0 +1,40 @@
+import type { MessageRecord } from "./messages.js";
+
+export interface ChatMessageCorrection { revision: number; editedAt?: number; deletedAt?: number; changedBy: string }
+export type ChatMessageChange = { expectedRevision: number; body: string } | { expectedRevision: number; deleted: true };
+export class ChatMessageCorrectionError extends Error {
+  constructor(public readonly status: 400 | 403 | 404 | 409, message: string) { super(message); }
+}
+export function readChatMessageCorrection(metadata: unknown): ChatMessageCorrection | undefined {
+  const value = (metadata as { chatCorrection?: unknown } | null)?.chatCorrection;
+  if (!value || typeof value !== "object") return;
+  const item = value as ChatMessageCorrection;
+  if (!Number.isSafeInteger(item.revision) || item.revision < 1 || typeof item.changedBy !== "string") return;
+  return { revision: item.revision, changedBy: item.changedBy,
+    ...(typeof item.editedAt === "number" && Number.isFinite(item.editedAt) ? { editedAt: item.editedAt } : {}),
+    ...(typeof item.deletedAt === "number" && Number.isFinite(item.deletedAt) ? { deletedAt: item.deletedAt } : {}) };
+}
+export function parseChatMessageChange(value: unknown): ChatMessageChange {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ChatMessageCorrectionError(400, "Invalid message change.");
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).length !== 2 || !Number.isSafeInteger(input.expectedRevision) || (input.expectedRevision as number) < 0) throw new ChatMessageCorrectionError(400, "Invalid message revision.");
+  if (input.deleted === true) return { expectedRevision: input.expectedRevision as number, deleted: true };
+  if (typeof input.body !== "string" || !input.body.trim() || input.body.length > 32_000) throw new ChatMessageCorrectionError(400, "Message must contain between 1 and 32000 characters.");
+  return { expectedRevision: input.expectedRevision as number, body: input.body };
+}
+
+/** A correction affects the shared record, never a new delivery or invocation. */
+export function correctChatMessage<T extends Pick<MessageRecord, "actorId" | "body"> & {
+  metadata?: MessageRecord["metadata"] | null; attachments?: unknown[]; mentions?: unknown[]; speech?: unknown;
+}>(message: T, input: unknown, actorId: string, canModerate: boolean, now: number): T {
+  const change = parseChatMessageChange(input);
+  const prior = readChatMessageCorrection(message.metadata);
+  const deleting = "deleted" in change;
+  if (message.actorId !== actorId && !(deleting && canModerate)) throw new ChatMessageCorrectionError(403, "Only the author can edit this message. Hosts can also delete messages.");
+  if ((prior?.revision ?? 0) !== change.expectedRevision) throw new ChatMessageCorrectionError(409, "This message changed since you opened it. Review the latest version before trying again.");
+  if (prior?.deletedAt != null) throw new ChatMessageCorrectionError(409, "This message has already been deleted.");
+  const correction: ChatMessageCorrection = { ...prior, revision: (prior?.revision ?? 0) + 1, changedBy: actorId, ...(deleting ? { deletedAt: now } : { editedAt: now }) };
+  return { ...message, body: deleting ? "" : change.body,
+    ...(deleting ? { attachments: [], mentions: [], speech: undefined } : {}),
+    metadata: { ...message.metadata, chatCorrection: correction } };
+}

package/src/chat-pins.ts

@@ -0,0 +1,40 @@
+/** Channel-visible references, distinct from a person's private saved messages. */
+export interface ChatPin {
+  messageId: string;
+  pinnedBy: string;
+  pinnedAt: number;
+}
+export interface ChatPinChange { messageId: string; pinned: boolean }
+
+export function readChatPins(value: unknown): ChatPin[] {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set<string>();
+  return value.filter((item): item is ChatPin => {
+    if (!item || typeof item !== "object" || typeof item.messageId !== "string" || !item.messageId
+      || typeof item.pinnedBy !== "string" || !item.pinnedBy || typeof item.pinnedAt !== "number"
+      || !Number.isFinite(item.pinnedAt) || seen.has(item.messageId)) return false;
+    seen.add(item.messageId);
+    return true;
+  }).map(({ messageId, pinnedBy, pinnedAt }) => ({ messageId, pinnedBy, pinnedAt }));
+}
+
+export function parseChatPinChange(value: unknown): ChatPinChange {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid channel pin change.");
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).length !== 2 || typeof input.messageId !== "string" || !input.messageId
+    || input.messageId.trim() !== input.messageId || input.messageId.length > 256 || typeof input.pinned !== "boolean") {
+    throw new Error("Invalid channel pin change.");
+  }
+  return { messageId: input.messageId, pinned: input.pinned };
+}
+
+export function applyChatPinChange(current: unknown, change: unknown, actorId: string, now: number): ChatPin[] {
+  const input = parseChatPinChange(change);
+  const pins = readChatPins(current);
+  if (!input.pinned) return pins.filter(pin => pin.messageId !== input.messageId);
+  // An idempotent repeat must not rewrite who originally pinned the message.
+  if (pins.some(pin => pin.messageId === input.messageId)) return pins;
+  if (pins.length >= 50) throw new Error("Channel pin limit reached. Unpin a message before adding another.");
+  if (!actorId || !Number.isFinite(now)) throw new Error("Invalid pin attribution.");
+  return [...pins, { messageId: input.messageId, pinnedBy: actorId, pinnedAt: now }];
+}

package/src/common.ts

@@ -65,6 +65,8 @@ export type DeliveryTransport =
   | "pairing_bridge"
   | "peer_broker"
   | "http"
+  | "mcp_poll"
+  | "devin_cloud_cli"
   | "webhook"
   | "telegram"
   | "discord"

package/src/events.ts

@@ -61,6 +61,8 @@ export type MessagePostedEvent = ControlEventBase<"message.posted", {
   message: MessageRecord;
 }>;
 
+export type MessageCorrectedEvent = ControlEventBase<"message.corrected", { message: MessageRecord }>;
+
 export type ConversationReadCursorUpdatedEvent = ControlEventBase<"conversation.read_cursor.updated", {
   cursor: ConversationReadCursor;
 }>;
@@ -122,6 +124,7 @@ export type ControlEvent =
   | ConversationUpsertedEvent
   | BindingUpsertedEvent
   | MessagePostedEvent
+  | MessageCorrectedEvent
   | ConversationReadCursorUpdatedEvent
   | InvocationRequestedEvent
   | FlightUpdatedEvent

package/src/herdr-workspace-digest.ts

@@ -29,6 +29,7 @@
  */
 
 import type {
+  HerdrAgentSessionRef,
   HerdrAgentStatus,
   HerdrPaneProjection,
   HerdrSessionTopology,
@@ -45,15 +46,19 @@ export type HerdrStatusCounts = Record<HerdrAgentStatus, number>;
 
 export type HerdrDigestPane = {
   /**
-   * What `herdr agent <verb>` accepts as a target for this pane: the stable
-   * terminal id when herdr reported one, else the pane id. Null on a persisted
-   * projection, where neither is live — a pane you cannot address yet.
+   * Observed host locator: terminal id when reported, else pane id. This is
+   * not a Scout address or a guaranteed CLI target (Herdr versions differ).
+   * Read handoffs use the host session + pane id. Null on a saved projection.
    */
   target: string | null;
   paneId: string;
   workspaceId: string;
   tabId: string;
+  /** Operator-assigned pane name, not a Scout agent address. */
+  name?: string | null;
   label: string | null;
+  /** Herdr-reported identity, not a verified Scout session binding. */
+  agentSession?: HerdrAgentSessionRef | null;
   /** Detected agent label ("claude", "codex"), or null for a plain shell. */
   agent: string | null;
   status: HerdrAgentStatus;
@@ -168,7 +173,9 @@ function toDigestPane(pane: HerdrPaneProjection): HerdrDigestPane {
     paneId: pane.paneId,
     workspaceId: pane.workspaceId,
     tabId: pane.tabId,
+    name: pane.name ?? null,
     label: pane.label,
+    agentSession: pane.agentSession,
     agent: pane.agent,
     status: pane.agentStatus,
     directory: paneDirectory(pane),
@@ -262,6 +269,10 @@ export function digestHerdrTopology(
       });
       for (const pane of tab.panes) {
         const digestPane = toDigestPane(pane);
+        if (!topology.running) {
+          digestPane.target = null;
+          digestPane.status = "unknown";
+        }
         counts[digestPane.status] += 1;
         if (digestPane.agent) agentTotal += 1;
         all.push(digestPane);
@@ -372,10 +383,14 @@ export function digestHerdrTopology(
  * every row buys nothing.
  */
 function paneLine(pane: HerdrDigestPane): string {
-  const parts = pane.label
-    ? [pane.label, pane.agent ?? "shell", pane.paneId]
+  const title = pane.name ?? pane.label;
+  const parts = title
+    ? [title, pane.agent ?? "shell", pane.paneId]
     : [pane.paneId, pane.agent ?? "shell"];
+  if (pane.name && pane.label && pane.name !== pane.label) parts.push(pane.label);
   if (pane.directory) parts.push(directoryName(pane.directory));
+  parts.push(pane.status);
+  if (pane.agentSession) parts.push(`reported ${pane.agentSession.agent} ${pane.agentSession.kind}:${pane.agentSession.value}`);
   if (pane.focused) parts.push("focused");
   return `  ${parts.join("  ")}`;
 }
@@ -422,9 +437,10 @@ export function renderHerdrWorkspaceDigest(digest: HerdrWorkspaceDigest): string
   // scanning reader never reaches a footnote, and these are the lines that stop
   // someone believing `unknown` meant done or that a stale layout was current.
   for (const note of digest.notes) lines.push(`  ${note}`);
+  lines.push(`  Observed ${new Date(digest.observedAt).toISOString()}; pane names are host labels, not Scout addresses.`);
 
   if (digest.needsYou.length) {
-    lines.push("", "Waiting on you");
+    lines.push("", "Requests");
     for (const pane of digest.needsYou) lines.push(paneLine(pane));
   }
   if (digest.working.length) {
@@ -439,6 +455,7 @@ export function renderHerdrWorkspaceDigest(digest: HerdrWorkspaceDigest): string
       const where = group.directory ? ` (${group.directory})` : "";
       const hidden = omittedLabel(group.omittedCounts);
       lines.push(`  ${group.name}${where} — ${total} pane${total === 1 ? "" : "s"} · ${countsLine(group.counts)}${hidden ? ` · ${hidden}` : ""}`);
+      for (const pane of group.panes) lines.push(`  ${paneLine(pane)}`);
     }
   }
 

package/src/host-integrations.ts

@@ -38,8 +38,8 @@ export const SCOUT_HOST_INTEGRATIONS: readonly ScoutHostIntegration[] = [
     roles: ["execution_harness", "agent_host", "mcp_host"],
     harness: "claude",
     homepage: "https://claude.ai/claude-code",
-    repositoryUrl: "https://github.com/arach/claude-scout",
-    installHint: "/plugin marketplace add arach/claude-scout",
+    repositoryUrl: "https://github.com/oscout/claude-scout",
+    installHint: "/plugin marketplace add oscout/claude-scout",
     summary: "Claude Code can run Scout-routed work as a harness and expose Scout through a host plugin.",
   },
   {
@@ -48,8 +48,8 @@ export const SCOUT_HOST_INTEGRATIONS: readonly ScoutHostIntegration[] = [
     roles: ["execution_harness", "agent_host", "mcp_host"],
     harness: "codex",
     homepage: "https://github.com/openai/codex",
-    repositoryUrl: "https://github.com/arach/codex-scout",
-    installHint: "/plugin marketplace add arach/codex-scout",
+    repositoryUrl: "https://github.com/oscout/codex-scout",
+    installHint: "/plugin marketplace add oscout/codex-scout",
     summary: "Codex can run Scout-routed work as a harness and expose Scout through MCP/plugin surfaces.",
   },
   {
@@ -57,8 +57,8 @@ export const SCOUT_HOST_INTEGRATIONS: readonly ScoutHostIntegration[] = [
     label: "Cursor",
     roles: ["execution_harness", "agent_host", "mcp_host"],
     harness: "cursor",
-    repositoryUrl: "https://github.com/arach/cursor-scout",
-    installHint: "See https://github.com/arach/cursor-scout for the host-specific installer.",
+    repositoryUrl: "https://github.com/oscout/cursor-scout",
+    installHint: "See https://github.com/oscout/cursor-scout for the host-specific installer.",
     summary: "Cursor is an agent host and execution target when routed through its supported CLI or MCP surfaces.",
   },
   {

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./conversations.js";
 export * from "./conversation-projection.js";
 export * from "./channel-identity.js";
 export * from "./channel-invites.js";
+export * from "./channel-membership.js";
 export * from "./channel-reception.js";
 export * from "./collaboration.js";
 export * from "./assigned-roles.js";
@@ -61,3 +62,12 @@ export * from "./terminal-host-topology.js";
 export * from "./herdr-workspace-digest.js";
 export * from "./broker-routes.js";
 export * from "./rendezvous.js";
+
+export * from "./chat-pins.js";
+export * from "./chat-message-corrections.js";
+
+export * from "./chat-mentions.js";
+
+export * from "./agent-notifications.js";
+
+export * from "./mcp-core-tools.js";

package/src/invocations.ts

@@ -27,8 +27,12 @@ export type InvocationSessionPolicy =
   /** @deprecated use reuse */
   | "any";
 
-/** Where a newly created harness session should be discoverable. */
-export type SessionPlacement = "background" | "foreground";
+/**
+ * Where a newly created harness session should be discoverable.
+ * `attached` (Codex only) runs the session on an already-running Codex
+ * app-server (the daemon control socket) instead of a Scout-spawned one.
+ */
+export type SessionPlacement = "background" | "foreground" | "attached";
 
 export type InvocationForkSourceKind =
   | "native_thread_clone"
@@ -72,6 +76,17 @@ export interface InvocationExecutionPreference {
   forkFromSessionId?: ScoutId;
   forkContext?: InvocationForkContextOptions;
   lineage?: InvocationSessionLineage;
+  /**
+   * Hard per-turn execution budget in milliseconds, honoured only by the ACP
+   * wrappers (Grok, Kimi, OpenCode, Devin, Cursor). Tmux, Claude stream-JSON,
+   * Codex app-server, and Pi RPC do not implement a turn budget. Distinct
+   * from the requester's wait budget (`timeoutMs`): a caller willing to wait
+   * 24 h does not license a 24 h turn. When set it takes precedence over the
+   * OPENSCOUT_ACP_HARD_CEILING_MS default (typically to raise it); bounded to
+   * 6 h at the command boundary and always clamped to the administrator
+   * maximum OPENSCOUT_ACP_HARD_CEILING_MAX_MS (default 6 h).
+   */
+  turnBudgetMs?: number;
 }
 
 export interface InvocationRequest {
@@ -158,7 +173,7 @@ function cleanTraceTimestamp(value: unknown): number | undefined {
 }
 
 function cleanTracePlacement(value: unknown): SessionPlacement | undefined {
-  return value === "background" || value === "foreground" ? value : undefined;
+  return value === "background" || value === "foreground" || value === "attached" ? value : undefined;
 }
 
 function parseFlightSessionTraceEntry(value: unknown): FlightSessionTraceEntry | null {

package/src/mcp-core-tools.ts

@@ -0,0 +1,46 @@
+/**
+ * The `mcp:core` tool tier: what the hosted MCP gateway (mcp.oscout.net)
+ * exposes to a remote client through the bridge. The bridge filters on these
+ * names, the gateway's agent guide counts them, and the public docs list them.
+ * Titles and access must match the registered tools; a desktop test enforces it.
+ */
+export type ScoutMcpCoreToolAccess = "read" | "write";
+
+export type ScoutMcpCoreTool = {
+  name: string;
+  title: string;
+  access: ScoutMcpCoreToolAccess;
+  summary: string;
+};
+
+export const SCOUT_MCP_CORE_TOOL_CATALOG = [
+  { name: "whoami", title: "Scout Whoami", access: "read", summary: "Show the Scout identity and broker this connection acts as." },
+  { name: "agents_search", title: "Search Scout Agents", access: "read", summary: "Find agents on the mesh that can take a request." },
+  { name: "agents_resolve", title: "Resolve Scout Agent", access: "read", summary: "Resolve one agent handle, or report why it is ambiguous." },
+  { name: "ask", title: "Ask", access: "write", summary: "Ask an agent to answer, review, or build something, and get a handle to follow." },
+  { name: "invocations_get", title: "Get Scout Ask", access: "read", summary: "Read the current state of an ask." },
+  { name: "invocations_wait", title: "Wait For Scout Ask", access: "read", summary: "Wait briefly for an ask to finish and return its state." },
+  { name: "messages_send", title: "Send Scout Message", access: "write", summary: "Send a direct message or a channel post." },
+  { name: "messages_reply", title: "Reply to Scout Message", access: "write", summary: "Reply inside an existing conversation." },
+  { name: "messages_inbox", title: "Read Scout Inbox", access: "read", summary: "Read recent messages addressed to this identity." },
+  { name: "messages_channel", title: "Read Scout Channel", access: "read", summary: "Read recent messages in a named channel." },
+  { name: "current_reply_context", title: "Current Scout Reply Context", access: "read", summary: "Check whether a reply would continue an inbound ask." },
+  { name: "broker_feed", title: "Read Agent Broker Feed", access: "read", summary: "Read one agent's messages, deliveries, and errors in one view." },
+  { name: "tail_events", title: "Read Tail Events", access: "read", summary: "Read recent activity from the coding agents on the Scout machine." },
+  { name: "labels_brief", title: "Brief Scout Label", access: "read", summary: "Summarize the records that share a label." },
+  { name: "labels_feed", title: "Read Scout Label Feed", access: "read", summary: "Read the event backlog for a label." },
+  { name: "work_update", title: "Update Scout Work", access: "write", summary: "Move a work item through progress, review, and done." },
+  { name: "notify_operator", title: "Notify Operator", access: "write", summary: "Send the human operator a non-blocking note." },
+  { name: "consult_operator", title: "Consult Operator Without Blocking", access: "write", summary: "Ask the operator for advice while continuing with a stated default." },
+  { name: "feedback_send", title: "Send Scout Feedback", access: "write", summary: "Report a bug or rough edge in Scout to the OpenScout team." },
+  { name: "sessions_attach", title: "Attach External Session", access: "write", summary: "Give this conversation a Scout mailbox so agents can reply to it." },
+  { name: "sessions_get", title: "Get External Session", access: "read", summary: "Read the mailbox attached to this conversation." },
+  { name: "sessions_poll", title: "Poll External Session", access: "read", summary: "Read pending items in the attached mailbox." },
+  { name: "sessions_ack", title: "Acknowledge External Session Item", access: "write", summary: "Mark a mailbox item as received." },
+  { name: "sessions_reply", title: "Reply to External Session Item", access: "write", summary: "Send the final answer for a delivered task." },
+] as const satisfies readonly ScoutMcpCoreTool[];
+
+export type ScoutMcpCoreToolName = (typeof SCOUT_MCP_CORE_TOOL_CATALOG)[number]["name"];
+
+export const SCOUT_MCP_CORE_TOOL_NAMES: readonly ScoutMcpCoreToolName[] =
+  SCOUT_MCP_CORE_TOOL_CATALOG.map((tool) => tool.name);