@openscout/protocol 0.2.64 → 0.2.83

package/src/scout-composer.ts

@@ -0,0 +1,249 @@
+import { parseAgentIdentity } from "./agent-identity.js";
+import { AGENT_HARNESSES, type AgentHarness } from "./actors.js";
+import type { ScoutRouteTarget } from "./scout-dispatch.js";
+
+export const SCOUT_COMPOSER_ROUTE_OPERATOR = ">>" as const;
+export const SCOUT_TARGET_HANDLE_SHORTHAND = "⌖" as const;
+
+export type ScoutComposerRouteDiagnosticCode =
+  | "missing_target"
+  | "invalid_target";
+
+export interface ScoutComposerRouteDiagnostic {
+  code: ScoutComposerRouteDiagnosticCode;
+  message: string;
+  start: number;
+  end: number;
+}
+
+export interface ScoutComposerRoute {
+  operator: typeof SCOUT_COMPOSER_ROUTE_OPERATOR;
+  token: string;
+  target: ScoutRouteTarget;
+  operatorStart: number;
+  operatorEnd: number;
+  targetStart: number;
+  targetEnd: number;
+}
+
+export interface ScoutComposerRouteParseResult {
+  route: ScoutComposerRoute | null;
+  body: string;
+  diagnostics: ScoutComposerRouteDiagnostic[];
+}
+
+const WHITESPACE_PATTERN = /\s/;
+const TRAILING_TARGET_PUNCTUATION_PATTERN = /[.,!?;)\]}]+$/;
+const ROUTE_VALUE_PATTERN = /^\S+$/;
+const AGENT_LABEL_START_PATTERN = /^[A-Za-z0-9]/;
+const SESSION_ROUTE_HARNESSES = new Set<AgentHarness>(AGENT_HARNESSES);
+
+function findRouteOperator(input: string): { start: number; end: number } | null {
+  let searchFrom = 0;
+
+  while (searchFrom < input.length) {
+    const index = input.indexOf(SCOUT_COMPOSER_ROUTE_OPERATOR, searchFrom);
+    if (index === -1) {
+      return null;
+    }
+
+    const previous = index > 0 ? input[index - 1] : "";
+    if (index === 0 || WHITESPACE_PATTERN.test(previous)) {
+      return {
+        start: index,
+        end: index + SCOUT_COMPOSER_ROUTE_OPERATOR.length,
+      };
+    }
+
+    searchFrom = index + SCOUT_COMPOSER_ROUTE_OPERATOR.length;
+  }
+
+  return null;
+}
+
+function routeBodyWithoutTarget(input: string, start: number, end: number): string {
+  return `${input.slice(0, start)} ${input.slice(end)}`.replace(/\s+/g, " ").trim();
+}
+
+function trimRouteTargetToken(value: string): string {
+  return value
+    .trim()
+    .replace(TRAILING_TARGET_PUNCTUATION_PATTERN, "");
+}
+
+function isRouteValue(value: string): boolean {
+  return value.length > 0 && ROUTE_VALUE_PATTERN.test(value);
+}
+
+function parseAgentLabelTarget(value: string): ScoutRouteTarget | null {
+  const label = value.replace(/^@+/, "");
+  if (!AGENT_LABEL_START_PATTERN.test(label)) {
+    return null;
+  }
+  if (!parseAgentIdentity(label)) {
+    return null;
+  }
+  return { kind: "agent_label", label, value };
+}
+
+function parseTargetHandleTarget(rawValue: string): ScoutRouteTarget | null {
+  const handle = rawValue.replace(/^[@⌖]+/, "");
+  if (!isRouteValue(handle)) {
+    return null;
+  }
+  return { kind: "target_handle", handle, value: `target:${handle}` };
+}
+
+function parseRouteAliasTarget(rawValue: string): ScoutRouteTarget | null {
+  const alias = rawValue.replace(/^@+/, "").trim().toLowerCase();
+  if (!isRouteValue(alias)) return null;
+  return { kind: "route_alias", alias, value: `alias:${alias}` };
+}
+
+function parseSessionRouteTarget(rawValue: string): ScoutRouteTarget | null {
+  const value = rawValue.replace(/^@+/, "");
+  if (!isRouteValue(value)) {
+    return null;
+  }
+
+  const harnessSeparator = value.indexOf(":");
+  if (harnessSeparator > 0) {
+    const maybeHarness = value.slice(0, harnessSeparator) as AgentHarness;
+    const sessionId = value.slice(harnessSeparator + 1);
+    if (SESSION_ROUTE_HARNESSES.has(maybeHarness) && isRouteValue(sessionId)) {
+      return {
+        kind: "session_id",
+        sessionId,
+        harness: maybeHarness,
+        value: `session:${maybeHarness}:${sessionId}`,
+      };
+    }
+  }
+
+  return { kind: "session_id", sessionId: value, value: `session:${value}` };
+}
+
+function parsePrefixedRouteTarget(prefix: string, rawValue: string): ScoutRouteTarget | null {
+  const value = rawValue.replace(/^@+/, "");
+  if (!isRouteValue(value)) {
+    return null;
+  }
+
+  if (prefix === "agent" || prefix === "a") {
+    return parseAgentLabelTarget(value);
+  }
+  if (prefix === "alias" || prefix === "route-alias" || prefix === "route_alias") {
+    return parseRouteAliasTarget(rawValue);
+  }
+  if (prefix === "target" || prefix === "target-handle" || prefix === "target_handle") {
+    return parseTargetHandleTarget(rawValue);
+  }
+  if (prefix === "ref" || prefix === "binding" || prefix === "binding-ref") {
+    return { kind: "binding_ref", ref: value, value: `ref:${value}` };
+  }
+  if (prefix === "project" || prefix === "project-path" || prefix === "project_path") {
+    return { kind: "project_path", projectPath: value, value: `project:${value}` };
+  }
+  if (prefix === "id" || prefix === "agent-id" || prefix === "agent_id") {
+    return { kind: "agent_id", agentId: value, value: `id:${value}` };
+  }
+  if (prefix === "session" || prefix === "session-id" || prefix === "session_id" || prefix === "sid" || prefix === "s") {
+    return parseSessionRouteTarget(rawValue);
+  }
+  if (prefix === "channel" || prefix === "chan" || prefix === "ch") {
+    return { kind: "channel", channel: value, value: `channel:${value}` };
+  }
+
+  return null;
+}
+
+export function parseScoutComposerRouteTarget(value: string): ScoutRouteTarget | null {
+  const token = trimRouteTargetToken(value);
+  if (!isRouteValue(token)) {
+    return null;
+  }
+
+  if (token === "broadcast") {
+    return { kind: "broadcast", value: token };
+  }
+
+  if (token.startsWith(SCOUT_TARGET_HANDLE_SHORTHAND)) {
+    return parseTargetHandleTarget(token);
+  }
+
+  const separatorIndex = token.indexOf(":");
+  if (separatorIndex > 0) {
+    const prefix = token.slice(0, separatorIndex).toLowerCase();
+    const rawValue = token.slice(separatorIndex + 1);
+    const prefixed = parsePrefixedRouteTarget(prefix, rawValue);
+    if (prefixed) {
+      return prefixed;
+    }
+  }
+
+  return parseAgentLabelTarget(token);
+}
+
+export function parseScoutComposerRoute(input: string): ScoutComposerRouteParseResult {
+  const operator = findRouteOperator(input);
+  if (!operator) {
+    return {
+      route: null,
+      body: input.trim(),
+      diagnostics: [],
+    };
+  }
+
+  let targetStart = operator.end;
+  while (targetStart < input.length && WHITESPACE_PATTERN.test(input[targetStart] ?? "")) {
+    targetStart += 1;
+  }
+
+  if (targetStart >= input.length) {
+    return {
+      route: null,
+      body: routeBodyWithoutTarget(input, operator.start, operator.end),
+      diagnostics: [{
+        code: "missing_target",
+        message: "route operator requires a target after >>",
+        start: operator.start,
+        end: operator.end,
+      }],
+    };
+  }
+
+  let targetEnd = targetStart;
+  while (targetEnd < input.length && !WHITESPACE_PATTERN.test(input[targetEnd] ?? "")) {
+    targetEnd += 1;
+  }
+
+  const rawToken = input.slice(targetStart, targetEnd);
+  const token = trimRouteTargetToken(rawToken);
+  const target = parseScoutComposerRouteTarget(token);
+  if (!target) {
+    return {
+      route: null,
+      body: routeBodyWithoutTarget(input, operator.start, targetEnd),
+      diagnostics: [{
+        code: "invalid_target",
+        message: `invalid route target: ${rawToken}`,
+        start: targetStart,
+        end: targetEnd,
+      }],
+    };
+  }
+
+  return {
+    route: {
+      operator: SCOUT_COMPOSER_ROUTE_OPERATOR,
+      token,
+      target,
+      operatorStart: operator.start,
+      operatorEnd: operator.end,
+      targetStart,
+      targetEnd,
+    },
+    body: routeBodyWithoutTarget(input, operator.start, targetEnd),
+    diagnostics: [],
+  };
+}

package/src/scout-delivery.ts

@@ -1,23 +1,92 @@
 import type { ConversationDefinition } from "./conversations.js";
 import type { MetadataMap, ScoutId } from "./common.js";
+import type {
+  CollaborationAcceptanceState,
+  CollaborationPriority,
+  WorkItemRecord,
+} from "./collaboration.js";
 import type { FlightRecord, InvocationExecutionPreference } from "./invocations.js";
-import type { MessageRecord } from "./messages.js";
+import type { MessageAttachment, MessageRecord } from "./messages.js";
 import type {
   ScoutCallerContext,
   ScoutDispatchRecord,
   ScoutRoutePolicy,
   ScoutRouteTarget,
 } from "./scout-dispatch.js";
+import type { RouteAliasResolutionProof } from "./route-aliases.js";
+import type {
+  ScoutExecutionResolution,
+  ScoutRuntimeResolutionSource,
+} from "./runtime-execution.js";
 
 export type ScoutDeliverIntent = "tell" | "consult";
 
+export type ScoutOperatorSignalKind = "notify" | "consult" | "need";
+
+/**
+ * An agent-authored signal for its human operator.
+ *
+ * The three kinds are separated by what the agent does next, which is the only
+ * distinction the operator actually acts on:
+ *
+ *   notify  — FYI. The agent keeps going and expects nothing back.
+ *   consult — input would help, and the agent has already decided what it will
+ *             do without it (`defaultAction`). Silence is a valid answer.
+ *   need    — the agent cannot proceed. Silence is NOT an answer, so this is
+ *             the only kind that is blocking, and the only one that raises the
+ *             operator's needs-you surface.
+ *
+ * `notify` and `consult` stay conversational side effects: they never create a
+ * flight and never imply the agent is waiting. `need` is the exception on
+ * purpose — it is the agent declaring that the next move is yours.
+ *
+ * This is the declared counterpart to harness-level attention inference. An
+ * inferred stall says "something looks stuck"; a `need` says "here is exactly
+ * what I want from you", authored by the agent, and cannot be created without
+ * a question (enforced at the CLI boundary, not filtered downstream).
+ */
+export type ScoutOperatorSignal =
+  | {
+      kind: "notify";
+      blocking: false;
+      replyExpectation: "none";
+    }
+  | {
+      kind: "consult";
+      blocking: false;
+      replyExpectation: "optional";
+      defaultAction: string;
+    }
+  | {
+      kind: "need";
+      blocking: true;
+      replyExpectation: "required";
+      /** What the agent is asking for. Never empty — that is the whole point. */
+      question: string;
+      /** Optional discrete choices, when the answer is a selection. */
+      options?: string[];
+      /** Why the agent cannot continue without it. */
+      blockedReason?: string;
+    };
+
 export type ScoutDeliverRouteKind = "dm" | "channel" | "broadcast";
 
+export type ScoutProjectAgentPersistence = "one_time" | "sticky";
+
+export interface ScoutProjectAgentSpec {
+  persistence?: ScoutProjectAgentPersistence;
+  /** Human-addressable handle, without requiring the caller to include "@". */
+  handle?: string;
+}
+
 export type ScoutDeliveryRemediationKind =
   | "choose_target"
   | "register_target"
   | "wake_target"
   | "retry_later"
+  | "use_current_registration"
+  | "session_reference_not_attachable"
+  /** @deprecated use use_current_registration or session_reference_not_attachable */
   | "stale_reference";
 
 export type ScoutDeliverRejectReason =
@@ -32,20 +101,37 @@ export interface ScoutDeliverRequest {
   requesterId?: ScoutId;
   requesterNodeId?: ScoutId;
   body: string;
+  attachments?: MessageAttachment[];
   intent: ScoutDeliverIntent;
   target?: ScoutRouteTarget;
   targetLabel?: string;
   targetAgentId?: ScoutId;
+  targetSessionId?: ScoutId;
   routePolicy?: ScoutRoutePolicy;
   channel?: string;
   replyToMessageId?: ScoutId;
+  replyToSessionId?: ScoutId;
   speechText?: string;
   ensureAwake?: boolean;
   execution?: InvocationExecutionPreference;
+  executionSource?: Partial<Record<"harness" | "model" | "reasoningEffort", ScoutRuntimeResolutionSource>>;
+  projectAgent?: ScoutProjectAgentSpec;
+  labels?: string[];
   createdAt?: number;
   collaborationRecordId?: ScoutId;
+  workItem?: {
+    id?: ScoutId;
+    title: string;
+    summary?: string;
+    priority?: CollaborationPriority;
+    labels?: string[];
+    parentId?: ScoutId;
+    acceptanceState?: CollaborationAcceptanceState;
+    metadata?: MetadataMap;
+  };
   messageMetadata?: MetadataMap;
   invocationMetadata?: MetadataMap;
+  operatorSignal?: ScoutOperatorSignal;
 }
 
 export interface ScoutDeliveryReceipt {
@@ -54,12 +140,18 @@ export interface ScoutDeliveryReceipt {
   requesterId: ScoutId;
   requesterNodeId: ScoutId;
   targetAgentId?: ScoutId;
+  targetSessionId?: ScoutId;
   targetLabel?: string;
+  /** Provisional routable pointer (e.g. project-chopin) when target is cardless. */
+  sessionAlias?: string;
   bindingRef?: string;
   conversationId: ScoutId;
   messageId: ScoutId;
   flightId?: ScoutId;
+  /** Per-dimension requested/resolved launch truth available at acceptance. */
+  executionResolution?: ScoutExecutionResolution;
   acceptedAt: number;
+  aliasResolution?: RouteAliasResolutionProof;
 }
 
 export interface ScoutDeliveryRemediationAction {
@@ -78,17 +170,35 @@ export interface ScoutDeliverAcceptedResponse {
   conversation: ConversationDefinition;
   message: MessageRecord;
   targetAgentId?: ScoutId;
+  targetSessionId?: ScoutId;
+  sessionAlias?: string;
   bindingRef?: string;
+  aliasResolution?: RouteAliasResolutionProof;
   flight?: FlightRecord;
+  workItem?: WorkItemRecord;
 }
 
-export interface ScoutDeliverQuestionResponse {
+/**
+ * A routing clarification: delivery was not accepted and the caller is asked to
+ * clarify or re-route the carried {@link ScoutDispatchRecord}. This is unrelated to
+ * the collaboration `question` kind ({@link QuestionRecord}) — the `question` field
+ * here carries the dispatch, and the wire `kind` discriminant stays `"question"` for
+ * backward compatibility.
+ */
+export interface ScoutDeliverClarificationResponse {
   kind: "question";
   accepted: false;
   question: ScoutDispatchRecord;
   remediation?: ScoutDeliveryRemediationAction;
 }
 
+/**
+ * @deprecated Renamed to {@link ScoutDeliverClarificationResponse}. This routing
+ * clarification is distinct from the collaboration `question` kind. Retained as an
+ * alias for backward compatibility.
+ */
+export type ScoutDeliverQuestionResponse = ScoutDeliverClarificationResponse;
+
 export interface ScoutDeliverRejectedResponse {
   kind: "rejected";
   accepted: false;
@@ -99,5 +209,5 @@ export interface ScoutDeliverRejectedResponse {
 
 export type ScoutDeliverResponse =
   | ScoutDeliverAcceptedResponse
-  | ScoutDeliverQuestionResponse
+  | ScoutDeliverClarificationResponse
   | ScoutDeliverRejectedResponse;

package/src/scout-dispatch.ts

@@ -1,11 +1,23 @@
-import type { WakePolicy } from "./actors.js";
+import type { AgentHarness, WakePolicy } from "./actors.js";
 import type { AdvertiseScope, DeliveryTransport, MetadataMap, ScoutId } from "./common.js";
+import type { RouteAliasDiagnosticCode, RouteAliasResolutionProof, RouteAliasScope } from "./route-aliases.js";
 
 export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable" | "unavailable";
 
 export type ScoutCandidateEndpointState = "online" | "offline" | "unknown";
 
-export type ScoutRouteTargetKind = "agent_id" | "agent_label" | "binding_ref" | "channel" | "broadcast";
+export type ScoutRouteTargetKind =
+  | "agent_id"
+  | "agent_label"
+  | "existing_handle"
+  | "runtime_profile"
+  | "route_alias"
+  | "target_handle"
+  | "session_id"
+  | "binding_ref"
+  | "project_path"
+  | "channel"
+  | "broadcast";
 
 export type ScoutRouteAmbiguousPolicy = "reject" | "ask";
 
@@ -21,19 +33,36 @@ export interface ScoutCallerContext {
 export type ScoutRouteTarget =
   | { kind: "agent_id"; agentId: ScoutId; value?: string }
   | { kind: "agent_label"; label: string; value?: string }
+  | { kind: "existing_handle"; handle: string; value?: string }
+  | {
+      kind: "runtime_profile";
+      profile: string;
+      projectPath: string;
+      reasoningEffort?: string;
+      value?: string;
+    }
+  | { kind: "route_alias"; alias: string; scope?: RouteAliasScope; bindingId?: ScoutId; value?: string }
+  | { kind: "target_handle"; handle: string; value?: string }
+  | { kind: "session_id"; sessionId: ScoutId; harness?: AgentHarness; value?: string }
   | { kind: "binding_ref"; ref: string; value?: string }
+  | { kind: "project_path"; projectPath: string; value?: string }
   | { kind: "channel"; channel: string; value?: string }
   | { kind: "broadcast"; value?: string };
 
 export interface ScoutRoutePolicy {
   preferLocalNodeId?: ScoutId;
   ambiguous?: ScoutRouteAmbiguousPolicy;
+  allowHistoricalDirectId?: boolean;
+  /** @deprecated use allowHistoricalDirectId */
   allowStaleDirectId?: boolean;
 }
 
 export type ScoutDispatchUnavailableReason =
   | "manual_wake_required"
   | "retired"
+  | "superseded_registration"
+  | "session_reference_not_attachable"
+  /** @deprecated use superseded_registration or session_reference_not_attachable */
   | "stale_registration"
   | "unknown";
 
@@ -72,6 +101,8 @@ export interface ScoutDispatchEnvelope {
   target?: ScoutDispatchUnavailableTarget;
   dispatchedAt: number;
   dispatcherNodeId: ScoutId;
+  diagnosticCode?: RouteAliasDiagnosticCode;
+  aliasResolution?: RouteAliasResolutionProof;
 }
 
 export interface ScoutDispatchRecord extends ScoutDispatchEnvelope {