@openscout/protocol 0.2.64 → 0.2.83

package/dist/scout-delivery.d.ts

@@ -1,11 +1,65 @@
 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 ScoutDeliveryRemediationKind = "choose_target" | "register_target" | "wake_target" | "retry_later" | "stale_reference";
+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 = "unknown_target" | "ambiguous_target" | "invalid_target" | "missing_target";
 export interface ScoutDeliverRequest {
     id?: ScoutId;
@@ -13,20 +67,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 {
     requestId: ScoutId;
@@ -34,12 +105,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 {
     kind: ScoutDeliveryRemediationKind;
@@ -56,15 +133,32 @@ 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;
@@ -72,4 +166,5 @@ export interface ScoutDeliverRejectedResponse {
     rejection: ScoutDispatchRecord;
     remediation?: ScoutDeliveryRemediationAction;
 }
-export type ScoutDeliverResponse = ScoutDeliverAcceptedResponse | ScoutDeliverQuestionResponse | ScoutDeliverRejectedResponse;
+export type ScoutDeliverResponse = ScoutDeliverAcceptedResponse | ScoutDeliverClarificationResponse | ScoutDeliverRejectedResponse;
+//# sourceMappingURL=scout-delivery.d.ts.map

package/dist/scout-delivery.d.ts.map

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

package/dist/scout-dispatch.d.ts

@@ -1,8 +1,9 @@
-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";
 export interface ScoutCallerContext {
     actorId?: ScoutId;
@@ -20,10 +21,39 @@ export type ScoutRouteTarget = {
     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;
@@ -35,9 +65,13 @@ export type ScoutRouteTarget = {
 export interface ScoutRoutePolicy {
     preferLocalNodeId?: ScoutId;
     ambiguous?: ScoutRouteAmbiguousPolicy;
+    allowHistoricalDirectId?: boolean;
+    /** @deprecated use allowHistoricalDirectId */
     allowStaleDirectId?: boolean;
 }
-export type ScoutDispatchUnavailableReason = "manual_wake_required" | "retired" | "stale_registration" | "unknown";
+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";
 export interface ScoutDispatchCandidate {
     agentId: ScoutId;
     displayName: string;
@@ -71,6 +105,8 @@ export interface ScoutDispatchEnvelope {
     target?: ScoutDispatchUnavailableTarget;
     dispatchedAt: number;
     dispatcherNodeId: ScoutId;
+    diagnosticCode?: RouteAliasDiagnosticCode;
+    aliasResolution?: RouteAliasResolutionProof;
 }
 export interface ScoutDispatchRecord extends ScoutDispatchEnvelope {
     id: ScoutId;
@@ -78,3 +114,4 @@ export interface ScoutDispatchRecord extends ScoutDispatchEnvelope {
     conversationId?: ScoutId;
     requesterId?: ScoutId;
 }
+//# sourceMappingURL=scout-dispatch.d.ts.map

package/dist/scout-dispatch.d.ts.map

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

package/dist/scout-reply-context.d.ts

@@ -11,3 +11,4 @@ export interface ScoutReplyContext {
     replyPath: ScoutReplyPath;
     action?: InvocationAction;
 }
+//# sourceMappingURL=scout-reply-context.d.ts.map

package/dist/scout-reply-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scout-reply-context.d.ts","sourceRoot":"","sources":["../src/scout-reply-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B"}

package/dist/session-display-state.d.ts

@@ -0,0 +1,132 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+export type ScoutSessionDisplayPhase = "idle" | "running" | "waiting" | "failed" | "completed";
+export interface ScoutDisplayMessage {
+    id: ScoutId;
+    role: "user" | "assistant" | "system";
+    text?: string;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export interface ScoutDisplayTool {
+    id: ScoutId;
+    name: string;
+    status: "running" | "completed" | "failed";
+    summary?: string;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export interface ScoutDisplayAttentionItem {
+    id: ScoutId;
+    kind: "question" | "approval" | "permission" | "waiting";
+    title: string;
+    summary?: string;
+    sourceRef?: string;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export interface ScoutDisplaySubagent {
+    id: ScoutId;
+    agentType?: string;
+    title: string;
+    status: "running" | "completed" | "failed";
+    summary?: string;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export interface ScoutDisplayTask {
+    id: ScoutId;
+    title: string;
+    status: "pending" | "in_progress" | "completed";
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export interface ScoutDisplayUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    source?: "provider_exact" | "tokenizer_estimate" | "char_heuristic" | "manual_estimate";
+}
+export interface ScoutDisplayTurn {
+    id: ScoutId;
+    status: "streaming" | "completed" | "interrupted" | "error";
+    startedAt: number;
+    endedAt?: number;
+    blockCount: number;
+    messageCount: number;
+    toolCount: number;
+    attentionCount: number;
+    summary?: string;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export interface ScoutSessionDisplayState {
+    sessionId: ScoutId;
+    phase: ScoutSessionDisplayPhase;
+    currentMessage: ScoutDisplayMessage | null;
+    activeTools: Record<ScoutId, ScoutDisplayTool>;
+    attention: Record<ScoutId, ScoutDisplayAttentionItem>;
+    activeSubagents: Record<ScoutId, ScoutDisplaySubagent>;
+    turns: ScoutDisplayTurn[];
+    tasks: ScoutDisplayTask[];
+    usage?: ScoutDisplayUsage;
+    updatedAt: number;
+    metadata?: MetadataMap;
+}
+export type ScoutSessionDisplayEvent = {
+    type: "phase_changed";
+    phase: ScoutSessionDisplayPhase;
+    at: number;
+} | {
+    type: "message_updated";
+    message: ScoutDisplayMessage;
+    at?: number;
+} | {
+    type: "tool_started";
+    tool: ScoutDisplayTool;
+    at?: number;
+} | {
+    type: "tool_finished";
+    toolId: ScoutId;
+    failed?: boolean;
+    summary?: string;
+    at: number;
+} | {
+    type: "attention_opened";
+    item: ScoutDisplayAttentionItem;
+    at?: number;
+} | {
+    type: "attention_closed";
+    itemId: ScoutId;
+    at: number;
+} | {
+    type: "subagent_started";
+    subagent: ScoutDisplaySubagent;
+    at?: number;
+} | {
+    type: "subagent_finished";
+    subagentId: ScoutId;
+    failed?: boolean;
+    summary?: string;
+    at: number;
+} | {
+    type: "turns_snapshot";
+    turns: ScoutDisplayTurn[];
+    at: number;
+} | {
+    type: "tasks_snapshot";
+    tasks: ScoutDisplayTask[];
+    at: number;
+} | {
+    type: "usage_updated";
+    usage: ScoutDisplayUsage;
+    at: number;
+} | {
+    type: "reset_thread";
+    at: number;
+};
+export declare function createScoutSessionDisplayState(input: {
+    sessionId: ScoutId;
+    now?: number;
+}): ScoutSessionDisplayState;
+export declare function reduceScoutSessionDisplayState(state: ScoutSessionDisplayState, event: ScoutSessionDisplayEvent): ScoutSessionDisplayState;
+//# sourceMappingURL=session-display-state.d.ts.map

package/dist/session-display-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-display-state.d.ts","sourceRoot":"","sources":["../src/session-display-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,wBAAwB,GAChC,MAAM,GACN,SAAS,GACT,SAAS,GACT,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;CACzF;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,OAAO,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,wBAAwB,CAAC;IAChC,cAAc,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC/C,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC;IACtD,eAAe,EAAE,MAAM,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;IACvD,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1F;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,yBAAyB,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAClG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,wBAAwB,CAY3B;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,wBAAwB,EAC/B,KAAK,EAAE,wBAAwB,GAC9B,wBAAwB,CA8E1B"}

package/dist/session-display-state.js

@@ -0,0 +1,94 @@
+export function createScoutSessionDisplayState(input) {
+    return {
+        sessionId: input.sessionId,
+        phase: "idle",
+        currentMessage: null,
+        activeTools: {},
+        attention: {},
+        activeSubagents: {},
+        turns: [],
+        tasks: [],
+        updatedAt: input.now ?? 0,
+    };
+}
+export function reduceScoutSessionDisplayState(state, event) {
+    switch (event.type) {
+        case "phase_changed":
+            return { ...state, phase: event.phase, updatedAt: event.at };
+        case "message_updated":
+            return { ...state, currentMessage: event.message, updatedAt: event.at ?? event.message.updatedAt };
+        case "tool_started":
+            return {
+                ...state,
+                activeTools: { ...state.activeTools, [event.tool.id]: event.tool },
+                updatedAt: event.at ?? event.tool.updatedAt,
+            };
+        case "tool_finished": {
+            const current = state.activeTools[event.toolId];
+            if (!current)
+                return { ...state, updatedAt: event.at };
+            return {
+                ...state,
+                activeTools: {
+                    ...state.activeTools,
+                    [event.toolId]: {
+                        ...current,
+                        status: event.failed ? "failed" : "completed",
+                        summary: event.summary ?? current.summary,
+                        updatedAt: event.at,
+                    },
+                },
+                updatedAt: event.at,
+            };
+        }
+        case "attention_opened":
+            return {
+                ...state,
+                phase: state.phase === "idle" ? "waiting" : state.phase,
+                attention: { ...state.attention, [event.item.id]: event.item },
+                updatedAt: event.at ?? event.item.updatedAt,
+            };
+        case "attention_closed": {
+            const next = { ...state.attention };
+            delete next[event.itemId];
+            return {
+                ...state,
+                attention: next,
+                phase: state.phase === "waiting" && Object.keys(next).length === 0 ? "idle" : state.phase,
+                updatedAt: event.at,
+            };
+        }
+        case "subagent_started":
+            return {
+                ...state,
+                activeSubagents: { ...state.activeSubagents, [event.subagent.id]: event.subagent },
+                updatedAt: event.at ?? event.subagent.updatedAt,
+            };
+        case "subagent_finished": {
+            const current = state.activeSubagents[event.subagentId];
+            if (!current)
+                return { ...state, updatedAt: event.at };
+            return {
+                ...state,
+                activeSubagents: {
+                    ...state.activeSubagents,
+                    [event.subagentId]: {
+                        ...current,
+                        status: event.failed ? "failed" : "completed",
+                        summary: event.summary ?? current.summary,
+                        updatedAt: event.at,
+                    },
+                },
+                updatedAt: event.at,
+            };
+        }
+        case "turns_snapshot":
+            return { ...state, turns: [...event.turns], updatedAt: event.at };
+        case "tasks_snapshot":
+            return { ...state, tasks: [...event.tasks], updatedAt: event.at };
+        case "usage_updated":
+            return { ...state, usage: event.usage, updatedAt: event.at };
+        case "reset_thread":
+            return createScoutSessionDisplayState({ sessionId: state.sessionId, now: event.at });
+    }
+}

package/dist/terminal-host-topology.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Herdr session topology, projected for Scout clients.
+ *
+ * Herdr owns the real thing: workspaces, tabs, panes, layouts, and the agent
+ * records inside them. This type is a READ-ONLY PROJECTION of that topology —
+ * what Scout's terminals view needs to represent a herdr session faithfully
+ * without becoming a second layout manager. Layout coordinates and split
+ * ratios are included read-only so a client can render the arrangement
+ * faithfully; there are deliberately no mutation verbs here: if a client wants
+ * to change the topology, the handoff is the herdr client itself (`herdr
+ * session attach`, `herdr agent focus`), not a Scout control.
+ *
+ * The server builds this from `herdr --session <n> workspace list`,
+ * `tab list`, and `pane list` JSON, plus the per-tab layout geometry from
+ * `herdr --session <n> api snapshot`. A session whose server is stopped
+ * projects as `{ running: false, workspaces: [] }` — an ordinary state, not
+ * an error.
+ */
+/** Agent state as herdr reports it, never as Scout infers it. */
+export type HerdrAgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+/**
+ * The harness-native session reference herdr reports for a pane (e.g. a Claude
+ * session id). Opaque to Scout: carried so clients can correlate, never parsed.
+ */
+export type HerdrAgentSessionRef = {
+    agent: string;
+    kind: string;
+    source: string;
+    value: string;
+};
+export type HerdrPaneProjection = {
+    paneId: string;
+    /** Herdr's stable terminal id; `herdr agent <verb>` accepts it as a target. */
+    terminalId: string | null;
+    tabId: string;
+    workspaceId: string;
+    label: string | null;
+    /** Detected/reported agent label, e.g. "claude". Null for plain shells. */
+    agent: string | null;
+    agentStatus: HerdrAgentStatus;
+    agentSession: HerdrAgentSessionRef | null;
+    cwd: string | null;
+    foregroundCwd: string | null;
+    focused: boolean;
+    /**
+     * Scrollback position as herdr reports it. `maxOffsetFromBottom` is the
+     * pane's backlog depth — the cheapest activity signal the projection has.
+     * Null when the host does not report scroll state (older herdr).
+     */
+    scroll: HerdrPaneScroll | null;
+};
+export type HerdrPaneScroll = {
+    maxOffsetFromBottom: number;
+    offsetFromBottom: number;
+    viewportRows: number;
+};
+/**
+ * Layout geometry for one tab, read from `herdr api snapshot`. Rects are
+ * absolute terminal cell coordinates as herdr reports them (the area includes
+ * herdr's chrome offset); clients normalize against `area` to render a
+ * proportional replica.
+ */
+export type HerdrLayoutRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type HerdrLayoutPane = {
+    paneId: string;
+    focused: boolean;
+    rect: HerdrLayoutRect;
+};
+export type HerdrLayoutSplit = {
+    id: string | null;
+    direction: "right" | "down" | null;
+    ratio: number | null;
+    rect: HerdrLayoutRect | null;
+};
+export type HerdrTabLayout = {
+    tabId: string;
+    workspaceId: string;
+    area: HerdrLayoutRect;
+    focusedPaneId: string | null;
+    zoomed: boolean;
+    panes: HerdrLayoutPane[];
+    splits: HerdrLayoutSplit[];
+};
+export type HerdrTabProjection = {
+    tabId: string;
+    workspaceId: string;
+    label: string | null;
+    number: number | null;
+    focused: boolean;
+    agentStatus: HerdrAgentStatus;
+    panes: HerdrPaneProjection[];
+    /** Per-tab pane geometry; null when the snapshot did not cover this tab. */
+    layout: HerdrTabLayout | null;
+};
+export type HerdrWorkspaceProjection = {
+    workspaceId: string;
+    label: string | null;
+    number: number | null;
+    focused: boolean;
+    activeTabId: string | null;
+    agentStatus: HerdrAgentStatus;
+    tabs: HerdrTabProjection[];
+};
+export type HerdrSessionTopology = {
+    /** Herdr session name, e.g. "openscout". */
+    session: string;
+    /** Whether the session's herdr server answered. */
+    running: boolean;
+    workspaces: HerdrWorkspaceProjection[];
+    /** Server wall-clock when the projection was observed. */
+    observedAt: number;
+};
+export declare function emptyHerdrSessionTopology(session: string, running: boolean): HerdrSessionTopology;
+//# sourceMappingURL=terminal-host-topology.d.ts.map

package/dist/terminal-host-topology.d.ts.map

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

package/dist/terminal-host-topology.js

@@ -0,0 +1,21 @@
+/**
+ * Herdr session topology, projected for Scout clients.
+ *
+ * Herdr owns the real thing: workspaces, tabs, panes, layouts, and the agent
+ * records inside them. This type is a READ-ONLY PROJECTION of that topology —
+ * what Scout's terminals view needs to represent a herdr session faithfully
+ * without becoming a second layout manager. Layout coordinates and split
+ * ratios are included read-only so a client can render the arrangement
+ * faithfully; there are deliberately no mutation verbs here: if a client wants
+ * to change the topology, the handoff is the herdr client itself (`herdr
+ * session attach`, `herdr agent focus`), not a Scout control.
+ *
+ * The server builds this from `herdr --session <n> workspace list`,
+ * `tab list`, and `pane list` JSON, plus the per-tab layout geometry from
+ * `herdr --session <n> api snapshot`. A session whose server is stopped
+ * projects as `{ running: false, workspaces: [] }` — an ordinary state, not
+ * an error.
+ */
+export function emptyHerdrSessionTopology(session, running) {
+    return { session, running, workspaces: [], observedAt: Date.now() };
+}