eidolon-ai-runtime-host-contract 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "eidolon-ai-runtime-host-contract",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "description": "Serializable runtime host protocol and injected effects shared by local and remote shells.",
+  "dependencies": {
+    "holarchy-eidolon-adapter": "0.2.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
+  },
+  "private": false
+}

package/src/ActorManagement.ts

@@ -0,0 +1,22 @@
+/** Original Actor lifecycle, distinct from closing a browser pane or deleting files. */
+export type ActorLifecycle = Readonly<{
+  state: 'active' | 'archived' | 'tombstoned';
+  revision: number;
+  changedAt?: number;
+}>;
+export type ActorManagementCommand = Readonly<{
+  commandId: string;
+  kind: 'archive_actor' | 'delete_actor';
+  expectedServerInstanceId: string;
+  expectedEpoch: string;
+  expectedLifecycleRevision: number;
+}>;
+/** Principal-scoped durable proof; a historical receipt does not overwrite the current lifecycle. */
+export type ActorManagementResult = Readonly<{
+  sessionId: string;
+  actorId: string;
+  commandId: string;
+  kind: ActorManagementCommand['kind'];
+  submittedEpoch: string;
+  lifecycle: Readonly<{state: 'archived' | 'tombstoned'; revision: number; changedAt: number}>;
+}>;

package/src/AgentAdapters.ts

@@ -0,0 +1,171 @@
+import type { ExecutionEnvironmentRef, ExecutionEnvironmentContext } from './ExecutionEnvironment';
+import type { HostRequest } from './HostPort';
+import type { ParticipantContextCut } from './Participant';
+/** Original external runtimes keep their own handles; these are never Native TaskSpace IDs. */
+export type AgentAdapterKind = 'codex' | 'claude' | 'grok';
+export type AgentAdapterSourceRef = Readonly<{
+    kind: 'agent-adapter';
+    daemonId: string;
+    adapterId: string;
+    revision: number;
+}>;
+export type AgentAdapterConfiguration = Readonly<{
+    provider: AgentAdapterKind;
+    name: string;
+    model: string;
+    environment: ExecutionEnvironmentRef;
+    enabled: boolean;
+}>;
+export type AgentAdapterRegistration = Readonly<{
+    source: AgentAdapterSourceRef;
+    configuration: AgentAdapterConfiguration;
+}>;
+export type AgentAdapterCapabilities = Readonly<{
+    submit: boolean;
+    interrupt: boolean;
+    observeOriginal: boolean;
+    nativeTaskSpace: false;
+    nativeActorHistory: false;
+    attachments: false;
+    artifacts: false;
+    tools: 'chat-only' | 'read-only';
+    context: 'retained' | 'explicit-cut';
+}>;
+export type AgentAdapterView = AgentAdapterRegistration & Readonly<{
+    canSubmit: boolean;
+    unavailableReason?: string;
+    installedVersion?: string;
+    access: 'unverified' | 'observed';
+    capabilities: AgentAdapterCapabilities;
+}>;
+export type AgentAdapterDirectory = Readonly<{
+    daemonId: string;
+    adapters: readonly AgentAdapterView[];
+}>;
+export type AgentExecutionHandle = Readonly<{
+    kind: 'agent-execution';
+    source: AgentAdapterSourceRef;
+    provider: AgentAdapterKind;
+    sessionId: string;
+    turnId?: string;
+}>;
+export type AgentExecutionState = 'queued' | 'sending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'unknown';
+export type AgentAdapterSendCommand = Readonly<{
+    source: AgentAdapterSourceRef;
+    bindingKey: string;
+    commandId: string;
+    text: string;
+    contextCut: ParticipantContextCut;
+}>;
+export type AgentExecutionSnapshot = Readonly<{
+    source: AgentAdapterSourceRef;
+    bindingKey: string;
+    commandId: string;
+    fingerprint: string;
+    revision: number;
+    state: AgentExecutionState;
+    handle?: AgentExecutionHandle;
+    result?: string;
+    errorCode?: string;
+    canInterrupt: boolean;
+}>;
+export type AgentAdapterConfigureCommand = Readonly<{
+    commandId: string;
+    adapterId: string;
+    expectedRevision: number;
+    configuration: AgentAdapterConfiguration;
+}>;
+export type AgentAdapterConfigureReceipt = Readonly<{
+    commandId: string;
+    adapterId: string;
+    revision: number;
+    fingerprint: string;
+}>;
+export type AgentAdapterSelector = Readonly<{
+    source: AgentAdapterSourceRef;
+    bindingKey: string;
+    commandId: string;
+}>;
+export type AgentAdapterInterruptCommand = AgentAdapterSelector & Readonly<{
+    controlId: string;
+    expectedRevision: number;
+}>;
+export type AgentDriverEvent = Readonly<{
+    kind: 'session';
+    sessionId: string;
+}> | Readonly<{
+    kind: 'handle';
+    handle: AgentExecutionHandle;
+}> | Readonly<{
+    kind: 'sending';
+}> | Readonly<{
+    kind: 'running';
+}>;
+export type AgentDriverResult = Readonly<{
+    state: 'completed';
+    handle: AgentExecutionHandle;
+    text: string;
+}> | Readonly<{
+    state: 'failed' | 'cancelled' | 'unknown';
+    handle?: AgentExecutionHandle;
+    errorCode: string;
+}>;
+export type AgentDriverInput = Readonly<{
+    command: AgentAdapterSendCommand;
+    configuration: AgentAdapterConfiguration;
+    environment: ExecutionEnvironmentContext;
+    sessionId?: string;
+}>;
+export type AgentDriver = Readonly<{
+    probe(provider: AgentAdapterKind): Promise<Readonly<{
+        installed: boolean;
+        version?: string;
+        capabilities: AgentAdapterCapabilities;
+    }>>;
+    start(input: AgentDriverInput, onEvent: (event: AgentDriverEvent) => Promise<void>): Readonly<{
+        result: Promise<AgentDriverResult>;
+        interrupt(): Promise<void>;
+        close(): Promise<void>;
+    }>;
+}>;
+export type AgentAdapterHost = Readonly<{
+    directory(request: HostRequest): Promise<AgentAdapterDirectory>;
+    configure(request: HostRequest, command: AgentAdapterConfigureCommand): Promise<AgentAdapterConfigureReceipt>;
+    configurationResult(request: HostRequest, commandId: string): Promise<AgentAdapterConfigureReceipt>;
+    send(request: HostRequest, command: AgentAdapterSendCommand): Promise<AgentExecutionSnapshot>;
+    observe(request: HostRequest, selector: AgentAdapterSelector): Promise<AgentExecutionSnapshot>;
+    interrupt(request: HostRequest, command: AgentAdapterInterruptCommand): Promise<AgentExecutionSnapshot>;
+    busy(workspaceKey: string): boolean;
+    close(): Promise<void>;
+}>;
+export type AgentAdapterBinding = Readonly<{
+    source: AgentAdapterSourceRef;
+    bindingKey: string;
+    sessionId?: string;
+}>;
+export type AgentAdapterExecutionRecord = Readonly<{
+    command: AgentAdapterSendCommand;
+    configuration: AgentAdapterConfiguration;
+    snapshot: AgentExecutionSnapshot;
+}>;
+export type AgentAdapterState = Readonly<{
+    version: 1;
+    revision: number;
+    registrations: readonly AgentAdapterRegistration[];
+    receipts: readonly AgentAdapterConfigureReceipt[];
+    bindings: readonly AgentAdapterBinding[];
+    executions: readonly AgentAdapterExecutionRecord[];
+    controls: readonly Readonly<{
+        controlId: string;
+        fingerprint: string;
+        source: AgentAdapterSourceRef;
+        bindingKey: string;
+        commandId: string;
+        state: 'sending' | 'accepted' | 'unknown';
+    }>[];
+}>;
+export type AgentAdapterStore = Readonly<{
+    read(): AgentAdapterState;
+    commit(expectedRevision: number, state: AgentAdapterState): void;
+    close(): void;
+}>;

package/src/AgentAdaptersWire.ts

@@ -0,0 +1,61 @@
+import type { AgentAdapterConfigureCommand, AgentAdapterConfigureReceipt, AgentAdapterDirectory, AgentAdapterSourceRef, AgentAdapterSendCommand, AgentAdapterSelector, AgentAdapterInterruptCommand, AgentExecutionHandle, AgentExecutionSnapshot, AgentAdapterConfiguration } from './AgentAdapters';
+import { parseExecutionEnvironmentRef, parseHostParticipantSendCommand, WireSchemaError } from './Schema';
+function object(value: unknown, keys: readonly string[]): Record<string, any> { if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !keys.includes(k)))
+    throw new WireSchemaError('agent_adapter'); return value as Record<string, any>; }
+function text(value: unknown, max = 256): asserts value is string { if (typeof value !== 'string' || !value || value.length > max)
+    throw new WireSchemaError('agent_adapter_text'); }
+function id(value: unknown): asserts value is string { text(value, 128); if (!/^[A-Za-z0-9_-]+$/.test(value))
+    throw new WireSchemaError('agent_adapter_id'); }
+function integer(value: unknown, min = 0): asserts value is number { if (!Number.isSafeInteger(value) || (value as number) < min)
+    throw new WireSchemaError('agent_adapter_revision'); }
+function flag(value: unknown): asserts value is boolean { if (typeof value !== 'boolean')
+    throw new WireSchemaError('agent_adapter_flag'); }
+function provider(value: unknown) { if (!['codex', 'claude', 'grok'].includes(String(value)))
+    throw new WireSchemaError('agent_adapter_provider'); }
+export function parseAgentAdapterSourceRef(value: unknown): AgentAdapterSourceRef { const v = object(value, ['kind', 'daemonId', 'adapterId', 'revision']); if (v.kind !== 'agent-adapter')
+    throw new WireSchemaError('agent_adapter_source'); id(v.daemonId); id(v.adapterId); integer(v.revision, 1); return value as AgentAdapterSourceRef; }
+export function parseAgentAdapterConfiguration(value: unknown): AgentAdapterConfiguration { const v = object(value, ['provider', 'name', 'model', 'environment', 'enabled']); provider(v.provider); text(v.name, 120); text(v.model); if (!/^[A-Za-z0-9][A-Za-z0-9_.:/-]*$/.test(v.model))
+    throw new WireSchemaError('agent_adapter_model'); parseExecutionEnvironmentRef(v.environment); flag(v.enabled); return value as AgentAdapterConfiguration; }
+export function parseAgentAdapterConfigureCommand(value: unknown): AgentAdapterConfigureCommand { const v = object(value, ['commandId', 'adapterId', 'expectedRevision', 'configuration']); id(v.commandId); id(v.adapterId); integer(v.expectedRevision); parseAgentAdapterConfiguration(v.configuration); return value as AgentAdapterConfigureCommand; }
+export function parseAgentAdapterConfigureReceipt(value: unknown): AgentAdapterConfigureReceipt { const v = object(value, ['commandId', 'adapterId', 'revision', 'fingerprint']); id(v.commandId); id(v.adapterId); integer(v.revision, 1); text(v.fingerprint); return value as AgentAdapterConfigureReceipt; }
+export function parseAgentAdapterSelector(value: unknown): AgentAdapterSelector { const v = object(value, ['source', 'bindingKey', 'commandId']); parseAgentAdapterSourceRef(v.source); text(v.bindingKey); id(v.commandId); return value as AgentAdapterSelector; }
+export function parseAgentAdapterInterruptCommand(value: unknown): AgentAdapterInterruptCommand { const v = object(value, ['source', 'bindingKey', 'commandId', 'controlId', 'expectedRevision']); parseAgentAdapterSelector({ source: v.source, bindingKey: v.bindingKey, commandId: v.commandId }); id(v.controlId); integer(v.expectedRevision, 1); return value as AgentAdapterInterruptCommand; }
+export function parseAgentAdapterSendCommand(value: unknown): AgentAdapterSendCommand { const v = object(value, ['source', 'bindingKey', 'commandId', 'text', 'contextCut']); parseAgentAdapterSourceRef(v.source); text(v.bindingKey); id(v.commandId); text(v.text, 65536); parseHostParticipantSendCommand({ bindingKey: v.bindingKey, commandId: v.commandId, text: v.text, contextCut: v.contextCut, recipient: { kind: 'member', ref: 'adapter-wire-validation', ownerScopeRef: 'adapter-wire-validation', bindingRef: 'validation', bindingDigest: 'validation', admissionRef: 'validation' } }); return value as AgentAdapterSendCommand; }
+export function parseAgentExecutionHandle(value: unknown): AgentExecutionHandle { const v = object(value, ['kind', 'source', 'provider', 'sessionId', 'turnId']); if (v.kind !== 'agent-execution')
+    throw new WireSchemaError('agent_execution_handle'); parseAgentAdapterSourceRef(v.source); provider(v.provider); text(v.sessionId); if (v.turnId !== undefined)
+    text(v.turnId); if (v.provider === 'codex' && !v.turnId)
+    throw new WireSchemaError('agent_execution_turn'); return value as AgentExecutionHandle; }
+export function parseAgentExecutionSnapshot(value: unknown): AgentExecutionSnapshot { const v = object(value, ['source', 'bindingKey', 'commandId', 'fingerprint', 'revision', 'state', 'handle', 'result', 'errorCode', 'canInterrupt']); parseAgentAdapterSelector({ source: v.source, bindingKey: v.bindingKey, commandId: v.commandId }); text(v.fingerprint); integer(v.revision, 1); flag(v.canInterrupt); if (!['queued', 'sending', 'running', 'completed', 'failed', 'cancelled', 'unknown'].includes(v.state))
+    throw new WireSchemaError('agent_execution_state'); if (v.handle !== undefined) {
+    const handle = parseAgentExecutionHandle(v.handle);
+    if (['kind', 'daemonId', 'adapterId', 'revision'].some(k => (handle.source as any)[k] !== v.source[k]))
+        throw new WireSchemaError('agent_execution_source');
+} if (v.state === 'completed' && (!v.handle || typeof v.result !== 'string'))
+    throw new WireSchemaError('agent_execution_result'); if (v.result !== undefined && (v.state !== 'completed' || typeof v.result !== 'string' || new TextEncoder().encode(v.result).byteLength > 8 * 1024 * 1024))
+    throw new WireSchemaError('agent_execution_result'); if (v.errorCode !== undefined)
+    text(v.errorCode); return value as AgentExecutionSnapshot; }
+export function parseAgentAdapterDirectory(value: unknown): AgentAdapterDirectory { const v = object(value, ['daemonId', 'adapters']); id(v.daemonId); if (!Array.isArray(v.adapters) || v.adapters.length > 128)
+    throw new WireSchemaError('agent_adapter_directory'); for (const row of v.adapters) {
+    const a = object(row, ['source', 'configuration', 'canSubmit', 'unavailableReason', 'installedVersion', 'access', 'capabilities']);
+    const ref = parseAgentAdapterSourceRef(a.source);
+    if (ref.daemonId !== v.daemonId)
+        throw new WireSchemaError('agent_adapter_source');
+    parseAgentAdapterConfiguration(a.configuration);
+    flag(a.canSubmit);
+    if (a.unavailableReason !== undefined)
+        text(a.unavailableReason);
+    if (a.installedVersion !== undefined)
+        text(a.installedVersion, 512);
+    if (!['unverified', 'observed'].includes(a.access))
+        throw new WireSchemaError('agent_adapter_access');
+    const c = object(a.capabilities, ['submit', 'interrupt', 'observeOriginal', 'nativeTaskSpace', 'nativeActorHistory', 'attachments', 'artifacts', 'tools', 'context']);
+    for (const key of ['submit', 'interrupt', 'observeOriginal'])
+        flag(c[key]);
+    for (const key of ['nativeTaskSpace', 'nativeActorHistory', 'attachments', 'artifacts'])
+        if (c[key] !== false)
+            throw new WireSchemaError('agent_adapter_capability');
+    if (!['retained', 'explicit-cut'].includes(c.context))
+        throw new WireSchemaError('agent_adapter_context');
+    if (!['chat-only', 'read-only'].includes(c.tools))
+        throw new WireSchemaError('agent_adapter_tools');
+} return value as AgentAdapterDirectory; }

package/src/Attachment.ts

@@ -0,0 +1,15 @@
+export type AttachmentMime = "text/plain" | "image/png" | "image/jpeg" | "image/webp"
+export type HostInputPart = Readonly<
+  | { type: "text"; text: string; filename?: string }
+  | { type: "image"; mime: Exclude<AttachmentMime, "text/plain">; dataUrl: string; filename?: string }
+  | { type: "attachment"; attachmentId: string }
+>
+export type AttachmentOperation = Readonly<
+  | { kind: "begin"; expectedEpoch: string; uploadId: string; filename: string; mime: AttachmentMime; totalBytes: number; digest: string }
+  | { kind: "append"; expectedEpoch: string; attachmentId: string; offsetBytes: number; data: string }
+  | { kind: "release"; expectedEpoch: string; attachmentId: string }
+>
+export type AttachmentSummary = Readonly<{
+  attachmentId: string; epoch: string; state: "uploading" | "ready" | "released" | "expired" | "failed"
+  filename: string; mime: AttachmentMime; uploadedBytes: number; totalBytes: number; expiresAt: number; digest?: string
+}>

package/src/Command.ts

@@ -0,0 +1,110 @@
+import type { HostInputPart } from "./Attachment"
+import type { ConversationOperation } from "./Conversation"
+import type { GoalControl, GoalControlReceipt, SessionGoalView } from "./Goal"
+export type ActorAction = "host_interaction" | "observe" | "read_history" | "send_text" | "cancel_turn" | "answer_question" | "set_model" | "compact" | "send_input" | "upload_attachment" | "set_work_mode" | "fork_conversation" | "rewind_conversation" | "set_goal" | "continue_goal" | "archive_actor" | "delete_actor"
+export type ActorExecutionKind = "primary" | "interactive" | "delegate" | "detached"
+export type TurnState = "queued" | "running" | "waiting_input" | "succeeded" | "failed" | "cancelled" | "interrupted"
+
+export type ProtocolError = Readonly<{
+  code: string
+  requestId: string
+  retryable: boolean
+  message?: string
+  currentEpoch?: string
+  state?: "unknown"
+}>
+
+export type CommandPayloads = {
+  host_interaction: { actorId: string; operationJson: string }
+  send_text: { actorId: string; text: string }
+  send_input: { actorId: string; parts: readonly HostInputPart[] }
+  cancel_turn: { actorId: string; turnId: string }
+  answer_question: { actorId: string; turnId: string; questionnaireId: string; responseText: string }
+  create_actor: { profileId: string; displayName?: string; modelRef?: string }
+  set_model: { actorId: string; modelRef: string }
+  compact: { actorId: string; expectedHistoryRevision: string }
+  set_work_mode: { actorId: string; workMode: "build" | "plan" }
+  set_goal: GoalControl
+  continue_goal: { actorId: string; goalId: string }
+  fork_conversation: { actorId: string; expectedHistoryRevision: string; selector: { kind: "current_head" } | { kind: "through_committed_message"; messageId: string } }
+  rewind_conversation: { actorId: string; expectedHistoryRevision: string; selector: { kind: "through_committed_message"; messageId: string } }
+}
+
+export type CommandEnvelope = {
+  [K in keyof CommandPayloads]: Readonly<{
+    commandId: string
+    surfaceId: string
+    expectedEpoch: string
+    kind: K
+    payload: Readonly<CommandPayloads[K]>
+  }>
+}[keyof CommandPayloads]
+
+export type AssociatedTurn = Readonly<{
+  actorId: string
+  turnId: string
+  state: TurnState
+  canCancel: boolean
+  pendingQuestionIds: readonly string[]
+  source?: "goal"
+  goalId?: string
+}>
+
+export type CommandReceipt = Readonly<{
+  commandId: string
+  epoch: string
+  status: "accepted"
+  turnId?: string
+  acceptedAt: string
+}>
+
+export type CommandStatus = Readonly<{
+  commandId: string
+  epoch: string
+  turnId?: string
+  state: "accepted" | "applied" | "rejected" | "unknown"
+  associatedTurn?: AssociatedTurn
+  result?: { actorId?: string; compact?: Readonly<{ compacted: boolean; tokensBefore: number; messagesAfter: number; historyRevision: string }>; workMode?: "build" | "plan"; conversation?: ConversationOperation; goal?: GoalControlReceipt }
+  error?: ProtocolError
+}>
+
+export type ExistingControl = Readonly<{
+  status: "existing_control"
+  epoch: string
+  requestedCommandId: string
+  existingControlId: string
+  actorId: string
+  turnId: string
+  questionnaireId?: string
+}>
+
+export type AlreadyTerminal = Readonly<{
+  status: "already_terminal"
+  epoch: string
+  requestedCommandId: string
+  associatedTurn: AssociatedTurn
+}>
+
+export type CommandAdmission = CommandReceipt | ExistingControl | AlreadyTerminal
+
+export type ActorSummary = Readonly<{
+  actorId: string
+  lifecycle?: import('./ActorManagement').ActorLifecycle
+  /** Stable identity within this session, only for fixed foreground actors. */
+  memberId?: string
+  displayName: string
+  executionKind: ActorExecutionKind
+  runtimeState: "idle" | "running" | "waiting_input" | "stopped" | "failed"
+  allowedActions: readonly ActorAction[]
+  capabilities: Readonly<{ textInput: boolean; cancelTurn: boolean; questionnaireAnswer: boolean }>
+  disabledReasons?: Readonly<Record<string, string>>
+  modelRef?: string
+  workContext?: Readonly<{ workMode: "build" | "plan"; taskPhase: "normal" | "answer"; workModeUpdatedAt: string; taskPhaseUpdatedAt: string }>
+  threadGoal?: SessionGoalView
+}>
+
+export type CreateSessionCommand = Readonly<{
+  commandId: string
+  profileId: string
+  expectedServerInstanceId: string
+}>

package/src/ContentRead.ts

@@ -0,0 +1,20 @@
+import type { MessagePreview } from "./Observation"
+
+export type HistoryPage = Readonly<{
+  actorId: string
+  epoch: string
+  historyRevision: string
+  messages: readonly MessagePreview[]
+  nextCursor?: string
+}>
+
+export type MessageContentChunk = Readonly<{
+  codec: "public-message-json-v1"
+  encoding: "base64"
+  messageId: string
+  historyRevision: string
+  offsetBytes: number
+  totalBytes: number
+  data: string
+  nextCursor?: string
+}>

package/src/Conversation.ts

@@ -0,0 +1,18 @@
+/** Public publication facts, separate from execution replay and private proof. */
+export type ConversationOperationResult =
+  | Readonly<{ kind: "fork"; targetSessionId: string; targetActorId: string; cutoffMessageId?: string; transactionId: string }>
+  | Readonly<{ kind: "rewind"; retainedMessageCount: number; removedMessageCount: number; cutoffMessageId: string; historyRevision: string; transactionId: string }>
+
+export type ConversationOperation = Readonly<{
+  operationId: string
+  sessionId: string
+  actorId: string
+  commandId: string
+  epoch: string
+  submittedEpoch: string
+  kind: "fork" | "rewind"
+  state: "pending" | "unknown" | "applied" | "rejected"
+  result?: ConversationOperationResult
+  errorCode?: string
+}>
+export type ConversationOperationList = Readonly<{ epoch: string; operations: readonly ConversationOperation[] }>

package/src/Daemon.ts

@@ -0,0 +1,63 @@
+import type { HostCapabilities, RuntimeHostPort } from './HostPort'
+import type { ResourceEffectKind } from './Effects'
+import type {HostRequest} from './HostPort'
+import type {WorkflowTaskTreeRelayIntent,WorkflowTaskTreeTrustedContext,WorkflowTaskTreeOwnerCall} from './WorkflowTaskTree'
+
+export type WorkspaceRegistration = Readonly<{
+  workspaceKey: string; workspaceId: string; workDir: string; revision: number; placement: 'workspace' | 'independent'
+}>
+export type DaemonCapabilities = Readonly<{
+  protocolVersion: '1'; mode: 'daemon'; daemonId: string; daemonInstanceId: string
+  globalWorkspaceKey: string; limits: { workspaces: number; workers: number; requests: number; subscriptions: number; sessionsPerWorkspace: number }
+}>
+export type WorkspaceView = WorkspaceRegistration & Readonly<{
+  state: 'registered' | 'opening' | 'ready' | 'closing' | 'failed'; serverInstanceId?: string; error?: string
+}>
+export const hostOperations = ['organizationWorkbench','organizationDirectory','previewOrganization','commandOrganization','organizationResult','hostInteractions','executionEnvironmentBusy','workflowDefinitions','workflowRuns','workflowRun','workflowEvents','commandWorkflow','workflowCommandResult','workflowMaterial','globalTaskCreateResult','globalTaskRootPlan','globalTaskDetail','globalTaskArtifact','globalTaskSpaces','globalTaskSpace','commandGlobalTaskSpace','globalTaskSpaceResult','participantDirectory', 'openParticipant', 'submitExecution', 'executionOutputPage', 'participantWork','controlParticipant','executionArtifact','participantAttachment', 'sessions', 'createSession', 'sessionMetadata', 'manageSession', 'sessionManagementResult',
+  'workflowMaterialFiles', 'workflowLaunchMaterials', 'workflowLaunch','workflowLaunchParameters','workflowAuthoring','workflowHumanReview','workflowSessionCall','workflowExecutionCatalog','workflowConversationOwner',
+  'actors', 'statistics', 'conversationOperations', 'conversationOperation', 'command', 'attachment',
+  'commandStatus', 'history', 'content', 'subscribe', 'isBusy'] as const
+export type HostOperation = typeof hostOperations[number]
+export type WorkerConfig = Readonly<{
+  workspace: WorkspaceRegistration; globalRoot: string; principalId: string; grantsVersion: string
+  globalAuthority?: Readonly<{daemonId:string;globalWorkspaceKey:string}>;
+  daemonAuthority?: Readonly<{daemonId:string;globalWorkspaceKey:string}>;
+  taskTreeEnabled?:boolean;
+  executionEnvironmentsEnabled?:boolean;
+  sessionLimit?: number
+  runtimeConfig?: { adapter?: string; model?: string; mcp?: boolean; metadata?: Record<string,unknown>; captureProviderRequests?: boolean; approvalMode?: 'default' | 'full-auto' | 'dangerous' }
+}>
+export type WorkerRequest =
+  | { kind: 'init'; config: WorkerConfig }
+  | { kind: 'call'; id: string; operation: HostOperation; args: unknown[] }
+  | { kind: 'pull' | 'unsubscribe'; id: string; subscriptionId: string }
+  | { kind: 'close'; id: string }
+  | { kind: 'prepare-close'; id: string }
+  | { kind: 'lease-result'; id: string; leaseId?: string; error?: string }
+  | { kind:'tasktree-owner-call';id:string;request:HostRequest;context:WorkflowTaskTreeTrustedContext;intent:WorkflowTaskTreeRelayIntent }
+  | { kind:'tasktree-relay-result';id:string;value?:unknown;error?:{status:number;code:string;state?:string} }
+  | {kind:'execution-environment-result';id:string;value?:import('./ExecutionEnvironment').ExecutionEnvironmentContext;error?:{status:number;code:string}}
+export type WorkerReply =
+  | { kind: 'ready'; capabilities: HostCapabilities }
+  | { kind: 'result'; id: string; value?: unknown; error?: { status: number; code: string; currentEpoch?: string; state?: string } }
+  | { kind: 'lease'; id: string; effect: ResourceEffectKind; targets?: readonly string[];workflowTaskTree?:import('./WorkflowTaskTree').WorkflowTaskTreeOrigin;executionEnvironment?:import('./ExecutionEnvironment').ExecutionEnvironmentRef;workflowMaterialRead?:import('./Effects').WorkflowMaterialReadOrigin;authorizationRead?:import('./Effects').HostAuthorizationReadOrigin }
+  | { kind: 'lease-cancel'; id: string }
+  | { kind: 'release' | 'invalidate'; leaseId: string }
+  | { kind:'tasktree-relay';id:string;request:HostRequest;intent:WorkflowTaskTreeRelayIntent }
+  | {kind:'execution-environment-resolve';id:string;request:HostRequest;ref:import('./ExecutionEnvironment').ExecutionEnvironmentRef;action:'read'|'execute'}
+export type WorkspaceWorker = Readonly<{
+  port: RuntimeHostPort; capabilities: HostCapabilities; exited: Promise<unknown>; close(force?: boolean): Promise<void>
+  taskTreeCall?:WorkflowTaskTreeOwnerCall;
+}>
+export type WorkspaceRegistryStore = Readonly<{
+  daemonId: string; list(): readonly WorkspaceRegistration[]
+  register(workDir: string, placement?: 'workspace' | 'independent'): Promise<WorkspaceRegistration>
+  remove(key: string): void; close(): void
+  resources: Readonly<{ uncertain(): readonly string[]; acquire(id: string, key: string): void; release(id: string): void; invalidate(key: string): void }>
+}>
+export type DaemonEffects = Readonly<{
+  registry: WorkspaceRegistryStore
+  canonicalDirectory(path: string): Promise<string>
+  createWorker(config: WorkerConfig): Promise<WorkspaceWorker>
+  newId(): string
+}>

package/src/Effects.ts

@@ -0,0 +1,61 @@
+import type { ActorAction } from "./Command"
+import type { ObservationFrame } from "./Observation"
+
+export type Principal = Readonly<{ principalId: string; grantsVersion: string }>
+export type AuthorizationTarget =
+  | Readonly<{kind:'workflow-materials';action:'read';path:string}>
+  | Readonly<{kind:'agent-adapters';action:'discover'|'configure'}>
+  | Readonly<{kind:'agent-adapter';adapterId:string;action:'observe'|'execute'|'interrupt'}>
+  | Readonly<{kind:'execution-environments';action:'discover'}>
+  | Readonly<{kind:'execution-environment';workspaceKey:string;action:'read'|'execute'}>
+  | Readonly<{kind:'daemon-schedules';action:'read'|'manage'|'execute';scheduleId?:string}>
+  | Readonly<{kind:'workflows';action:'discover'|'read'|'start'|'resume';runId?:string}>
+  | Readonly<{kind:'global-taskspaces';action:'list'|'create'}>
+  | Readonly<{kind:'global-taskspace';taskSpaceId:string;action:'read'|'edit'|'execute'|'control'}>
+  | Readonly<{ kind: "server"; action: "list_sessions" | "create_session" | "discover_sessions" | "manage_workspaces" | "stop_daemon" | "register_workflow_conversation_owner" }>
+  | Readonly<{ kind: "session"; sessionId: string; action: "open" | "import_session" | "create_actor" | "read_statistics" | "rename" | "archive" }>
+  | Readonly<{ kind: "actor"; sessionId: string; actorId: string; action: ActorAction }>
+
+export type HostAuthorizationEffects = Readonly<{
+  permits: (principal: Principal, target: AuthorizationTarget) => boolean
+  currentGrantsVersion: (principalId: string) => string | undefined
+}>
+
+export type HostIdentityEffects = Readonly<{
+  newId: () => string
+  now: () => number
+}>
+
+export type ResourceEffectKind = "read_only" | "workspace_mutation" | "unclassified"
+export type ResourceLease = Readonly<{ release: () => void; invalidate?: () => void }>
+export type WorkflowMaterialReadOrigin = Readonly<{ request: import('./HostPort').HostRequest; path: string }>
+export type HostAuthorizationReadOrigin = Readonly<{request:import('./HostPort').HostRequest;target:AuthorizationTarget}>
+export type HostResourceEffects = Readonly<{
+  acquire: (input: Readonly<{ workDir: string; kind: ResourceEffectKind; targets?: readonly string[]; signal?: AbortSignal;workflowTaskTree?:import('./WorkflowTaskTree').WorkflowTaskTreeOrigin;executionEnvironment?:import('./ExecutionEnvironment').ExecutionEnvironmentRef;workflowMaterialRead?:WorkflowMaterialReadOrigin;authorizationRead?:HostAuthorizationReadOrigin }>) => Promise<ResourceLease>
+}>
+
+export type SessionWriterLeaseEffects = Readonly<{
+  acquire: (sessionStorageKey: string) => Promise<ResourceLease>
+}>
+
+export type ObservationCursorBinding = Readonly<{
+  epoch: string
+  principalId: string
+  grantsVersion: string
+  actors: readonly string[]
+}>
+export type ObservationCursorEffects = Readonly<{
+  issue: (binding: ObservationCursorBinding, seq: number) => string
+  read: (binding: ObservationCursorBinding, cursor: string) => number | undefined
+}>
+
+export type ObservationQueue = Readonly<{
+  frames: AsyncIterable<ObservationFrame>
+  push: (frame: ObservationFrame, lane: "bootstrap" | "live") => boolean
+  close: () => void
+  isClosed: () => boolean
+}>
+export type ObservationQueueEffects = Readonly<{
+  create: (onClose: () => void) => ObservationQueue
+  frameBytes: (frame: ObservationFrame) => number
+}>

package/src/ExecutionEnvironment.ts

@@ -0,0 +1,28 @@
+import type { WorkspaceRegistration } from './Daemon';
+/** A reference to parent-owned registration, never a caller-provided filesystem path. */
+export type ExecutionEnvironmentRef = Readonly<{
+    kind: 'daemon-workspace';
+    daemonId: string;
+    workspaceKey: string;
+    revision: number;
+}>;
+export type ExecutionEnvironmentView = Readonly<{
+    ref: ExecutionEnvironmentRef;
+    name: string;
+    workDir: string;
+    state: 'registered' | 'opening' | 'ready' | 'closing' | 'failed';
+    canExecute: boolean;
+    unavailableReason?: string;
+}>;
+export type ExecutionEnvironmentDirectory = Readonly<{
+    daemonId: string;
+    environments: readonly ExecutionEnvironmentView[];
+}>;
+/** Trusted composition result: public input cannot create this context or replace its path. */
+export type ExecutionEnvironmentContext = Readonly<{
+    ref: ExecutionEnvironmentRef;
+    workspace: WorkspaceRegistration;
+}>;
+export type ExecutionEnvironmentEffects = Readonly<{
+    resolve(request: import('./HostPort').HostRequest, ref: ExecutionEnvironmentRef, action: 'read' | 'execute'): Promise<ExecutionEnvironmentContext>;
+}>;