Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
/** Shared agent.launch schema lets remote clients use typed RpcSendParams.
* The host honors an explicit surface or refuses it; migrated worktree.create startup-agent fields are stripped. */
import { AGENT_LAUNCH_SURFACES } from '../agent-launch-surface'
import { z } from 'zod'
import { isAgentSessionOptions } from '../agent-session-record'
import { parseAgentSessionOperationTimestamp } from '../agent-session-host-authority'
import { parsePaneKey } from '../stable-pane-id'
import { isValidHostTerminalTabId } from '../terminal-tab-id'
import { isTuiAgent } from '../tui-agent-config'
import type { TuiAgent } from '../tui-agent'
import { WorktreeCreate } from './worktree-create-params'
import { FolderWorkspaceCreate } from './folder-workspace-params'
import { LaunchSourceParam } from './launch-source-param'
import { TerminalTabIdParam } from './agent-session-params'
import { SessionId } from './structured-agent-session-params'
import { isStructuredAgentSessionIdFor } from '../structured-agent-session-create'
import { AgentLaunchAccountEnv } from '../agent-launch-account-env'
const LaunchAgent = z.custom<TuiAgent>(isTuiAgent, { message: 'Unknown TUI agent' })
/** A layout id the caller may get wrong without failing the launch: anything but a string is dropped. */
const tolerantTabLayoutId = z
.unknown()
.transform((value): string | undefined => (typeof value === 'string' ? value : undefined))
.optional()
export const AgentLaunchFields = z.object({
agent: LaunchAgent,
/** Caller-minted retry identity; optional forever for shipped clients. Never mint after an ambiguous launch:
* a fresh ID on retry would create another operation instead of replaying. */
operationId: z
.string()
.refine(
(value) => parseAgentSessionOperationTimestamp(value) !== null,
'Malformed launch operation id'
)
.optional(),
target: z.discriminatedUnion('kind', [
z.object({
kind: z.literal('existing'),
/** Any selector the runtime resolves, the same as every other worktree-addressed method. */
worktree: z.string().min(1, 'Missing worktree selector')
}),
z.object({
kind: z.literal('create-worktree'),
/** Preserve the worktree.create payload while stripping its migrated agent fields. */
create: WorktreeCreate
}),
z.object({
kind: z.literal('create-folder-workspace'),
/** The `folderWorkspace.create` request verbatim; its `createdWithAgent` is the launch's own. */
create: FolderWorkspaceCreate
})
]),
prompt: z
.object({
text: z.string(),
delivery: z.enum(['submit', 'draft'])
})
.optional(),
/** A chat seeds the options it accepts; a terminal launch reads the model, effort and mode. */
sessionOptions: z.record(z.string(), z.string()).optional(),
/** A saved launch choice; absent `sessionOptions`, a terminal applies it as flags too. */
chatOptions: z.record(z.string(), z.string()).refine(isAgentSessionOptions).optional(),
reuseTerminal: z.object({ handle: z.string().min(1, 'Missing terminal handle') }).optional(),
/** Nullable on purpose: `null` is "no arguments", absent is "use the settings default". */
agentArgs: z.string().nullable().optional(),
/** Terminal-only cwd; structured launches downgrade rather than silently ignoring it. */
cwd: z.string().min(1, 'Empty launch cwd').optional(),
launchSource: LaunchSourceParam.optional(),
/** Caller reserves identity, not placement; validate verbatim adoption so reservations match.
* Structured launches use its tab half as tabId; reused terminals ignore it. paneKey reports the actual pane.
* Tab IDs span workspaces, so mint a fresh UUID per launch. */
paneKey: z
.string()
.refine((value) => {
const pane = parsePaneKey(value)
return (
pane !== null &&
pane.tabId === pane.tabId.trim() &&
TerminalTabIdParam.safeParse(pane.tabId).success &&
isValidHostTerminalTabId(pane.tabId)
)
}, 'Malformed launch pane key')
.optional(),
/** Caller-reserved chat ID; refuse duplicates, ignore for terminal outcomes. The returned sessionId is authoritative. */
sessionId: SessionId.optional(),
/** View-only placement is outside replay identity and never fails launch: fall back from missing group to
* anchor group, then active group; drop unknown keys. Requires agent.launch.placement.v1; receipt reports placement. */
placement: z
.object({ groupId: tolerantTabLayoutId, afterTabId: tolerantTabLayoutId })
.optional()
.catch(undefined),
/** focused selects the tab; background leaves selection; absent reveals as before. Caller navigation defaults
* keep paired-device selection local. View-only, outside replay identity; unknown words read as absent. */
presentation: z
.unknown()
.transform((value): 'focused' | 'background' | undefined =>
value === 'focused' || value === 'background' ? value : undefined
)
.optional(),
/** Desktop-prepared Claude/Codex home for WSL orcad without account services. Terminal-only; chat warns and
* keeps its host home. Optional forever, outside replay identity; old hosts strip it and use their default. */
accountEnv: AgentLaunchAccountEnv.optional(),
/** Forward the launching user’s chat default when host settings belong to someone else (e.g. relayed phone).
* Explicit surface overrides it; feasibility still decides. Outside replay identity; old hosts use their own default. */
nativeChatDefault: z.boolean().optional(),
/** Explicit terminal runs CLI; proven-unsupported chat refuses before creation. Inside replay identity; unknown
* values refuse. Clients must gate on agent.launch.surface.v1 because older hosts strip this field. */
surface: z.enum(AGENT_LAUNCH_SURFACES).optional()
})
/** Caller IDs must retain the agent lane encoded by host-minted IDs. */
function refuseSessionIdForAnotherAgent(
launch: { agent: string; sessionId?: string | undefined },
ctx: z.RefinementCtx
): void {
if (launch.sessionId && !isStructuredAgentSessionIdFor(launch.agent, launch.sessionId)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ['sessionId'],
message: 'Launch session id must be named for its agent'
})
}
}
export const AgentLaunch = AgentLaunchFields.superRefine(refuseSessionIdForAnotherAgent)
export type AgentLaunchParams = z.infer<typeof AgentLaunch>
// A distinct method prevents an older receiver from silently dropping the replay requirement.
export const AgentLaunchReplay = AgentLaunchFields.required({ operationId: true }).superRefine(
refuseSessionIdForAnotherAgent
)