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
import type {
AgentSessionMutationResult,
AgentSessionWireRefusalCode
} from '../../../src/shared/agent-session-wire'
import type { AgentSessionRefusalReference } from '../../../src/shared/agent-session-wire-refusals'
import type { AgentJournalCursor } from '../../../src/shared/agent-session-journal-types'
import { structuredAgentSessionPayloadFingerprint } from '../../../src/shared/structured-agent-session-mutation'
import { agentSessionWriteNoticeParts } from '../../../src/shared/agent-session-refusal-notice'
import {
agentSessionRefusalFailure,
agentSessionThrownFailure,
agentSessionWriteKindForMethod,
readAgentSessionErrorRefusal,
type AgentSessionWriteKind
} from '../../../src/shared/agent-session-write-failure'
import { mobileAgentSessionWriteNoticeText } from './agent-session-write-notice-copy'
import { structuredSessionOperationId } from './structured-session-operation-id'
import { isRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity'
import type { RpcClient } from '../transport/rpc-client'
import { isLogicalClientCutoverError } from '../transport/stable-logical-rpc-client'
import { MOBILE_NATIVE_CHAT_MIN_WRITE_TIMEOUT_MS } from './native-chat/mobile-native-chat-send'
export const STRUCTURED_SEND_TIMEOUT_MS = 15_000
export type StructuredAgentSessionMutationCallResult<TValue> =
| { status: 'accepted'; value: TValue; cursor?: AgentJournalCursor }
| { status: 'refused'; code: AgentSessionWireRefusalCode; message: string }
| { status: 'failed'; message: string }
| { status: 'unknown' }
export type StructuredAgentSessionMutationResult<TValue> =
| { status: 'accepted'; value: TValue; sameFence: boolean }
| { status: 'rejected' }
| { status: 'unknown' }
export type StructuredAgentSessionMutate = <TValue>(
method: string,
fingerprintMethod: string,
fields: Record<string, unknown>
) => Promise<StructuredAgentSessionMutationResult<TValue>>
class AgentSessionRpcResponseError extends Error {
constructor(
readonly code: string,
message: string,
/** A thrown refusal's reason rides here; its message is only the bare code. */
readonly data?: unknown
) {
super(message)
}
}
export function agentSessionReadFailureRefusal(failure: unknown) {
return readAgentSessionErrorRefusal(
typeof failure === 'object' && failure !== null && 'error' in failure ? failure.error : failure
)
}
export function agentSessionReadRefusalText(refusal: AgentSessionRefusalReference): string {
return mobileAgentSessionWriteNoticeText(
agentSessionWriteNoticeParts(agentSessionRefusalFailure(refusal), 'read-history')
)
}
// Read refusal words from error data: thrown messages contain bare codes, and stream failures nest them under error.
export function agentSessionReadFailureText(failure: unknown): string {
const refusal = agentSessionReadFailureRefusal(failure)
if (refusal) {
return agentSessionReadRefusalText(refusal)
}
if (failure instanceof Error) {
return failure.message
}
return typeof failure === 'object' && failure !== null
? 'message' in failure
? String(failure.message ?? '')
: ''
: String(failure)
}
export async function callAgentSession<TResult>(
client: RpcClient,
method: string,
params: unknown,
timeoutMs = STRUCTURED_SEND_TIMEOUT_MS,
options?: { failWhenDisconnected?: boolean }
): Promise<TResult> {
const response = await client.sendRequest(method, params, {
timeoutMs,
budgetSpansConnect: true,
...(options?.failWhenDisconnected ? { failWhenDisconnected: true } : {})
})
if (!response.ok) {
throw new AgentSessionRpcResponseError(
response.error.code,
response.error.message,
response.error.data
)
}
return response.result as TResult
}
export function timeoutForDeadline(deadline: number | undefined): number | null {
if (deadline === undefined) {
return STRUCTURED_SEND_TIMEOUT_MS
}
const timeoutMs = deadline - Date.now()
return timeoutMs >= MOBILE_NATIVE_CHAT_MIN_WRITE_TIMEOUT_MS ? timeoutMs : null
}
/** A refused phone send goes back into the composer; there is no Retry control. */
function phoneWriteKind(
fingerprintMethod: string,
fields: Record<string, unknown>
): AgentSessionWriteKind {
const write = agentSessionWriteKindForMethod(fingerprintMethod, fields)
return write === 'send' ? 'composer-send' : write
}
export async function requestStructuredAgentSessionMutation<TValue>(args: {
client: RpcClient
method: string
fingerprintMethod: string
sessionId: string
expectedRuntimeFence: number
fields: Record<string, unknown>
clientOperationId?: string
timeoutMs?: number
agentName?: string
}): Promise<StructuredAgentSessionMutationCallResult<TValue>> {
const {
client,
method,
fingerprintMethod,
sessionId,
expectedRuntimeFence,
fields,
clientOperationId,
timeoutMs,
agentName
} = args
const context = agentName ? { agentName } : {}
try {
const result = await callAgentSession<AgentSessionMutationResult<TValue>>(
client,
method,
{
envelope: {
sessionId,
clientOperationId: clientOperationId ?? structuredSessionOperationId(),
expectedRuntimeFence,
payloadFingerprint: structuredAgentSessionPayloadFingerprint({
method: fingerprintMethod,
sessionId,
fields
})
},
...fields
},
timeoutMs
)
if (
!result.ok &&
(method === 'agentSession.cancel' || method === 'agentSession.conversationCommand') &&
result.refusal.code === 'agent_session_operation_unknown'
) {
return { status: 'unknown' }
}
return result.ok
? { status: 'accepted', value: result.value, cursor: result.cursor }
: {
status: 'refused',
code: result.refusal.code,
message: mobileAgentSessionWriteNoticeText(
agentSessionWriteNoticeParts(
agentSessionRefusalFailure(result.refusal),
phoneWriteKind(fingerprintMethod, fields),
context
)
)
}
} catch (error) {
const answered =
error instanceof AgentSessionRpcResponseError
? agentSessionThrownFailure(error, error.code)
: null
if (answered && answered.kind !== 'unconfirmed') {
// The host turned the request away before running it; its text is written for a log.
return {
status: 'failed',
message: mobileAgentSessionWriteNoticeText(
agentSessionWriteNoticeParts(answered, phoneWriteKind(fingerprintMethod, fields), context)
)
}
}
if (
isRpcDeliveryUnknown(error) ||
isLogicalClientCutoverError(error) ||
error instanceof AgentSessionRpcResponseError
) {
return { status: 'unknown' }
}
return {
status: 'failed',
message: mobileAgentSessionWriteNoticeText(
agentSessionWriteNoticeParts({ kind: 'failed' }, phoneWriteKind(fingerprintMethod, fields))
)
}
}
}