Files
orca/src/shared/orchestration-agent-reference.ts
T
Brennan Benson 3aa633d389 Mention an agent from the orchestration panel with one click (#34836)
* Add scoped terminal identity acquisition and preserve crew source wakes

* Share raw crew identity inputs through scoped production readers

* Exercise crew generation retirement through actual source owners

* Retire crew inputs on consumed ownership and visibility writes

* Use typed crew mutation and fixture access

* fix: use owned crew styles and committed render counters

* Repair crew fixture and RPC type contracts

* Align crew fixtures with pane and mention contracts

* Count crew consumer render attempts in the fixture

* Localize crew panel labels and details

* Align crew integration fixtures and RPC parameter contracts

* Keep mention contracts within their compiler boundaries

* Encapsulate terminal identity mutations and captured reader contracts

* Seed terminal identity fixtures through canonical mutations

* Complete crew panel English catalog entries

* Fix terminal identity fixture return type

* Cover terminal identity lifecycle schedules

* Align terminal fixtures with canonical identity sources

* Repair runtime fixture source contracts

* Use checked database fixtures for federation contracts

* Update crew source inventories and exit fixtures

* Preserve crew setup outcomes at existing subscription owners

* Match managed restore fixture to its nullable async return type

* Keep absent setup observations distinct from undefined failures

* Drive pending Crew questions from existing metadata

* Preserve nested pairing repair outcomes for shared callers

* Route attached workers to explicit local recipients

* Type Crew pending-question measurement receipts

* Match SSH repair fixture target absence to store contract

* Repair composer fixture and consolidate crew English catalog

* Add finite crew subscription boundary candidates

* Isolate crew portal in terminal file drop fixture

* test: use checked property access for crew owner assertions

* Consolidate web runtime auth type imports

* test: type crew API legacy arguments and pending results

* Bound cold terminal layout construction and finite pane acquisition

* test: use public runtime identity in pane acquisition fixture

* Follow image reference module relocation in mention serializer

* Avoid repeated searches in cold workspace layout loading

* Verify cold loader fault identity and hook claimant effects

* Revert "Route attached workers to explicit local recipients"

This reverts commit f1335d1c06.

Keep attached workers on the existing Run-home routing path for this change.

* Omit crew peer addresses outside the active home route

* Align crew disclosure and availability with shared UI

* Keep crew retries on the verified runtime session

* Bound cold layout retirement and recorded-key construction

* Verify original cold layout failure identity

* fix: preserve surviving layout split references

* test: use typed retirement instrumentation properties

* Keep crew overlay inside narrow panes

* Resume Crew streams on verified runtime sessions

* test: preserve pane and retirement fixture contracts with checked types

* Prepare Crew record admission and wake identity changes

* Derive Crew recipient actions from current target owners

* Keep nested Crew process facts within selected acquisition

* Defer Crew legacy facts to consumers and complete raw coverage on success

* Use deterministic time in Crew command fixtures

* Restore pane-local Crew menu dismissal focus

* Document schema-owned Dispatch row assertions

* test: align Crew authority fixtures with typed project boundaries

* Cover menu agent mentions through production insertion paths

* test: place Crew CLI integration in cross-surface project

* Type retained identity test meters with canonical source maps

* test: adapt mounted Crew fixture to Run unbind contract

* Document suffix Dispatch row boundary and preserve fixture unbinding

* Close crew menus when their terminal pane hides

* Remove unused structured activity component

* test: migrate Crew authority arguments and mailbox observations

* Forward native pane visibility to crew menus

* Keep rich draft offsets aligned with agent references

* Preserve later explicit pane selection after Mention delivery

* test: check the complete overlay focus host fixture

* test: use the DOM containment contract for menu focus

* Fix pointer dismissal enrollment and modal permission

* Remove shared menu primitive patches

* Reuse message avatars in the crew panel

* Focus the captured input when Mention is pressed

* Test the exact Mention all worker selection

* Derive Crew attention and actions from complete recipient authority

* test: repair Crew avatar store fixture and operation accounting

* Keep selected references structural during paste projection

* Fix Crew public-command fixture type contracts

* Align Crew fixtures with runtime reader and routing contracts

* Keep shared message avatar glyphs at their declared size

* fix: preserve existing native mention separators

* Narrow receiving fixture calls to unary RPC methods

* test: load crew Open sender before test execution

* test: consolidate pasted text value imports

* test: supply crew avatar panel mention contract

* Age pending question fixtures from every actual answer timestamp

* test: give mounted mention fixture a portable return type

* Complete Crew public-command workspace fixture result

* Test delegated helper follow-up through Crew advertised address

* Qualify Crew follow-up addresses through shared command admission

* Complete finite follow-up authority and lifetime evidence

* Assert exact remote authority acquisition error identity

* Consolidate Crew SQL test fixture imports

* Trim Crew panel tests to the high-impact set

Keep one mounted test per panel flow, the review-found regressions (avatar glyph size and attribution, stable labels, unavailable sending, hidden-pane menus, navigation remedies), the real producer-to-hook contract, cross-version refusal and recovery, and one N vs 10N contract per scaling piece. Remove permutation matrices, focus-timing proofs, and the duplicated web API and attempt suites.

* Trim Crew Mention tests to the high-impact set

Keep the native and terminal Mention flows, the review-found regressions (send and Goal serialization, label collisions, offsets and handback, Mention-all membership, press-time focus, late write responses, the native double space), the provider delivery contract, and the serializer N vs 10N bound. Remove menu and boundary permutation matrices, panel duplicates, recall and paste cases covered elsewhere, and the retained-group selection fixture. Panel-test cuts mirror the lower PR's so the stack merges cleanly.

* Trim Crew read-model tests to the high-impact set

Keep the real CLI/RPC/database command paths, one regression per review-found bug, the cross-version contracts and one N vs 10N operation contract per scaling piece. Drop permutation matrices, equivalence oracles, near-duplicate scenarios and diagnostic output, and return the SSH, managed-server and WSL test files to main, since their production changes were reverted earlier in this PR.

* Drop diagnostic output and a duplicate error case from Crew tests

Remove two leftover console.log diagnostics, an unused 2x2 sample matrix and unused return fields in the follow-up cost contract, and the subscription AbortError serialization case that the subscription identity and preload tests already cover.

* Pass the recorded-leaf reader in main's check-details loader test

* Build the approved orchestration panel design

Closed tab: panel icon, lineage icon with the worker count, then agents
grouped by status (needs you, working, idle, failed) with the sidebar's
status icon, up to three overlapping agent icons and +n. Rows are one
card with the task, the latest message or question, the relative time
and Details, Open, More. Rows sort by latest message. The open panel
reaches the pane top under the title strip. No user-visible 'crew'
text; counts use plurals. One store subscription resolves every row's
live sender state so the tab and the rows agree.

* Keep pane title buttons above the orchestration panel; tick row times

The open panel now sits just below the pane title strip in stacking
order and starts at the pane top in every host, so the strip's buttons
draw over its top band and no chat or terminal text shows above it. An
open panel lifts its pane's drag strip above it. Row times re-render on
the sidebar's shared 30s clock. Each status group keeps one fixed icon,
and the panel's needs-you count has its own plural.

* Move the orchestration row into its own file

* List every status case in the orchestration icon switches

* Name the orchestration row 'Mention <agent>:' while keeping its status, task and message

* Use the outline xs Button as is for Mention all

* Subscribe the memoized orchestration row to language changes; type the listener count

* Fit the orchestration tab and avatar stack to main's Button and key lint rules

* Ship the orchestration panel's plural counts in the runtime English catalog

* Subscribe the memoized crew row to language changes; read the nullable listener count

* Ship the orchestration panel's plural labels in the boot catalog

* End the chat's orchestration panel above the composer

The panel overlaid the whole chat body, so with it open the composer's
send button sat underneath it. The frame now wraps only the transcript;
the queued drafts, prompt cards and composer stay where main puts them.

* Skip escalations when choosing a crew row's latest message

Orca writes its failure notices (a worker stopped without reporting, a
chat agent error, a terminal exit) as the worker's own escalation, with
terminal, task and dispatch IDs and CLI syntax meant for the coordinator
agent. The panel showed that text as the row's second line. Only the
panel reads this query, so escalations are skipped there and the row
shows the agent's last real message. An agent's own Blocked escalation
is skipped too; it still reaches the coordinator's inbox.

* Point Mention's tests at the modules main moved

Main moved the composer command, send mutation and Claude dispatch
content modules; two of this PR's test files still imported the old
paths and failed to load. Also drop a mock of a module main removed.

* Say why a crew row's agent can't be opened

Opening a row whose agent is gone showed "This agent is no longer
available." Use the existing reasons instead: the chat is no longer on
this host, or the terminal has exited.

* End the panel above the composer in terminal-hosted chats too

A terminal's chat view still mounted the orchestration panel over the
whole chat, so it covered that view's composer and send button. Both
chat hosts now wrap their transcript in the same frame, which takes the
panel's props.

* Show only an agent's own words as a crew row's latest message

Besides failure notices, the latest line could pick up an empty setup
receipt (a blank line that also moved the row) or a lifecycle message
Orca rewrote to "Orca rejected this worker_done: ...". The panel's
query now admits only conversational types with a body and without the
lifecycle rejection marker, before choosing each peer's latest.

* Keep worker launch stages out of crew rows and Details

A row with no message fell back to the worker's internal launch stage
("input accepted", "worker report queued") as its second line, and
Details repeated it as Progress. The row now has no second line until
the agent says something, and Details drops Progress; the status icon
already shows the state.

* Fit both chat hosts under the line limit after the frame merge

Name each host's existing Mention availability once and pass it in the
frame's one-line crew props.

* Mention each agent once per chat draft

Mention all after a row Mention added a second chip for the same agent.
Inserting references now skips agents already in the draft or repeated
in the list; a repeat row click just focuses the composer. Terminal
Mention types text and is unchanged.

* Test a row Mention followed by Mention all

The QA sequence is two separate inserts; cover the draft scan that keeps
the first agent from being added again.

* Give the recipient-authority test's history message a body

The panel no longer admits empty-body messages as a row's latest; the
test's history message now carries the words a peer would send.

* Clip the chat's orchestration panel to its transcript

In a short split or under a tall composer, the transcript can be shorter
than the panel's header, which then painted over the composer. The chat
frame now clips the panel to the transcript; terminals are unchanged.

* Check a terminal's readiness when Mention is pressed

The panel read the terminal's connection once while rendering. A
restored pane connects later without a re-render, so its rows and
Mention all stayed disabled. Mention is now available whenever the pane
has a terminal, and the pane and connection are captured and checked
when the user presses it.

* Keep a row's status at full strength when it can't be mentioned

A row that couldn't be mentioned dimmed everything on it, including
another agent's "Waiting for you" line. Its content now stays as is;
only the hover highlight and pointer cursor go away.

* Translate the crew row Open failure toasts

The crew's Open failures were English literals. They now go through
translation, and a gone or outdated chat uses main's existing texts.

* Translate the crew row Open fallback for agents without a target

* Put the Orchestration panel behind an experimental setting, default off

Settings > Experimental > Orchestration panel (experimentalOrchestrationPanel).
Off mounts nothing: the chat frame, the terminal-hosted chat's identity lookup
and the terminal pane portals all gate where they mount, and toggling applies
live without remounting the transcript.

* Give the terminal-hosted chat's panel its own module

* Leave the setting-off path exactly as on main

The message card's avatar and its single-sender hook are back to main's code;
the panel keeps its own list hook. The panel's code now loads only when it
first mounts, behind the setting.

* Leave /goal and ordinary sends exactly as on main

A typed multi-line /goal is prose again, as on main; only Mention's own
routing lines after a one-line /goal join its objective. A draft with no
agent reference skips the reference serializer, so its send text is projected
once, as before. The routing line format now lives with the other reference
formats.

* Keep main's abort reason and send-failure handling for every web subscription

* Build the panel tests' settings from defaults instead of a cast

* Load the panel with plain lazy so a failed load never retries or reloads the app

* Keep main's /goal parser and put a goal's Mention notes on its one line

The shared command parser is main's code again, so any typed or pasted text
parses as before. A typed /goal or Goal-mode objective with mentions carries
its routing notes on the same line instead.

* Let a failed panel load try again the next time the panel mounts

* Type the queued-edit test's pending send as main's boolean result

* Keep a mention's routing notes in Goal mode on hosts without goals

There /goal goes to the agent as a message, so its notes keep their own lines,
as a typed /goal there already does. A draft with no mention sends main's text.

* Give the lazy panel test the Mention props this branch's panel requires
2026-11-02 00:41:40 -08:00

42 lines
1.5 KiB
TypeScript

import { parseOrcaSessionAddress } from './orca-session-address'
export type OrchestrationAgentReference = { label: string; address: string; hostKey: string }
export function isPublicOrchestrationAddress(address: string): boolean {
return (
/^(?:term_[a-zA-Z0-9_-]+|(?:dispatch|run):[a-zA-Z0-9_-]+)$/.test(address) ||
parseOrcaSessionAddress(address) !== null
)
}
export function printableAgentLabel(label: string): string {
return [...label.replace(/[\r\n\u2028\u2029]/g, ' ')]
.filter(
(char) =>
char.charCodeAt(0) >= 32 && !(char.charCodeAt(0) >= 127 && char.charCodeAt(0) <= 159)
)
.join('')
}
// Every printed reference carries this; a draft without it holds no agent reference.
const AGENT_REFERENCE_MARK = ' (Orca agent '
export function mayHoldAgentReferences(text: string): boolean {
return text.includes(AGENT_REFERENCE_MARK)
}
export function agentReferenceToken(reference: OrchestrationAgentReference): string {
return `@${reference.label}${AGENT_REFERENCE_MARK}${reference.address})`
}
/** The routing line a sent message ends with, one per mentioned agent. */
export function agentReferenceNote(label: string, address: string): string {
return `[Orca agent "${label}": ${address} — message it with orca orchestration send --to ${address}]`
}
export function terminalAgentReference(reference: OrchestrationAgentReference): string | null {
return isPublicOrchestrationAddress(reference.address)
? `${printableAgentLabel(reference.label)}${AGENT_REFERENCE_MARK}${reference.address}) `
: null
}