PaperClipAI/packages/plugins/sdk/src/protocol.ts

import type { PluginWorkspaceParams, PluginWorkspaceResult } from "./workspace-provider.js";
import type { PluginEnvironmentTaskParams, PluginEnvironmentTaskResult } from "./environment-tasks.js";
import type { PluginAgentRuntimeState, PluginAgentRuntimeIdentity } from "./types.js";
import type { AgentLifecycleRequest, AgentLifecycleResult } from "@paperclipai/shared";
import type { AiConnectionRouterRequest, AiConnectionRouterResult } from "@paperclipai/shared";
/**
 * JSON-RPC 2.0 message types and protocol helpers for the host ↔ worker IPC
 * channel.
 *
 * The Paperclip plugin runtime uses JSON-RPC 2.0 over stdio to communicate
 * between the host process and each plugin worker process. This module defines:
 *
 * - Core JSON-RPC 2.0 envelope types (request, response, notification, error)
 * - Standard and plugin-specific error codes
 * - Typed method maps for host→worker and worker→host calls
 * - Helper functions for creating well-formed messages
 *
 * @see PLUGIN_SPEC.md §12.1 — Process Model
 * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
 * @see https://www.jsonrpc.org/specification
 */

import type {
  PaperclipPluginManifestV1,
  PluginLauncherBounds,
  PluginLauncherRenderContextSnapshot,
  PluginLauncherRenderEnvironment,
  PluginStateScopeKind,
  Company,
  Project,
  Issue,
  IssueComment,
  IssueDocument,
  IssueDocumentSummary,
  IssueAssigneeAdapterOverrides,
  IssueAttachment,
  IssueThreadInteraction,
  CreateIssueThreadInteractionInput,
  Approval,
  PluginManagedAgentResolution,
  PluginManagedProjectResolution,
  PluginManagedRoutineResolution,
  PluginManagedSkillResolution,
  Routine,
  RoutineRun,
  Agent,
  Goal,
  PluginLocalFolderDeclaration,
  PrincipalPermissionGrant,
  ExternalObjectStatusCategory,
  ExternalObjectStatusTone,
  ExternalObjectLivenessState,
  ExternalObjectMentionConfidence,
  ExternalObjectMentionSourceKind,
  EnvSecretRefBinding,
} from "@paperclipai/shared";
export type { PluginLauncherRenderContextSnapshot } from "@paperclipai/shared";

import type {
  PluginEvent,
  ResourceLifecycleEvent,
  ResourceLifecycleResult,
  PluginIssueCheckoutOwnership,
  PluginIssueOrchestrationSummary,
  PluginIssueRelationSummary,
  PluginIssueSubtree,
  PluginIssueAttachmentContent,
  PluginIssueWakeupBatchResult,
  PluginIssueWakeupResult,
  PluginJobContext,
  PluginExecutionWorkspaceMetadata,
  PluginWorkspace,
  ToolRunContext,
  ToolResult,
  PluginLocalFolderListing,
  PluginLocalFolderStatus,
  PluginAccessInvite,
  PluginAccessMember,
  PluginAssignmentPreviewInput,
  PluginAuthorizationAuditEntry,
  PluginAuthorizationDecisionResult,
  PluginAuthorizationPolicyRecord,
  PluginAuthorizationPolicySummary,
} from "./types.js";
import type {
  PluginHealthDiagnostics,
  PluginApiRequestInput,
  PluginApiResponse,
  PluginConfigValidationResult,
  PluginWebhookInput,
} from "./define-plugin.js";

// ---------------------------------------------------------------------------
// JSON-RPC 2.0 — Core Protocol Types
// ---------------------------------------------------------------------------

/** The JSON-RPC protocol version. Always `"2.0"`. */
export const JSONRPC_VERSION = "2.0" as const;

/**
 * A unique request identifier. JSON-RPC 2.0 allows strings or numbers;
 * we use strings (UUIDs or monotonic counters) for all Paperclip messages.
 */
export type JsonRpcId = string | number;

/**
 * Host-owned scope attached to a host→worker invocation. Workers may echo the
 * invocation id on nested worker→host calls, but they never author this scope.
 */
export interface JsonRpcInvocationScope {
  readonly companyId?: string | null;
}

export interface JsonRpcInvocationContext {
  readonly id: string;
  readonly scope: JsonRpcInvocationScope;
}

/**
 * A JSON-RPC 2.0 request message.
 *
 * The host sends requests to the worker (or vice versa) and expects a
 * matching response with the same `id`.
 */
export interface JsonRpcRequest<
  TMethod extends string = string,
  TParams = unknown,
> {
  readonly jsonrpc: typeof JSONRPC_VERSION;
  /** Unique request identifier. Must be echoed in the response. */
  readonly id: JsonRpcId;
  /** The RPC method name to invoke. */
  readonly method: TMethod;
  /** Structured parameters for the method call. */
  readonly params: TParams;
  /**
   * Host-issued metadata for the top-level plugin invocation that is currently
   * executing. The worker treats this as opaque and echoes only the id on
   * worker→host calls made from the same async execution context.
   */
  readonly paperclipInvocation?: PluginInvocationContext;
  /** Opaque top-level invocation id echoed by worker→host requests. */
  readonly paperclipInvocationId?: string;
}

/**
 * A JSON-RPC 2.0 success response.
 */
export interface JsonRpcSuccessResponse<TResult = unknown> {
  readonly jsonrpc: typeof JSONRPC_VERSION;
  /** Echoed request identifier. */
  readonly id: JsonRpcId;
  /** The method return value. */
  readonly result: TResult;
  readonly error?: never;
}

/**
 * A JSON-RPC 2.0 error object embedded in an error response.
 */
export interface JsonRpcError<TData = unknown> {
  /** Machine-readable error code. */
  readonly code: number;
  /** Human-readable error message. */
  readonly message: string;
  /** Optional structured error data. */
  readonly data?: TData;
}

/**
 * A JSON-RPC 2.0 error response.
 */
export interface JsonRpcErrorResponse<TData = unknown> {
  readonly jsonrpc: typeof JSONRPC_VERSION;
  /** Echoed request identifier. */
  readonly id: JsonRpcId | null;
  readonly result?: never;
  /** The error object. */
  readonly error: JsonRpcError<TData>;
}

/**
 * A JSON-RPC 2.0 response — either success or error.
 */
export type JsonRpcResponse<TResult = unknown, TData = unknown> =
  | JsonRpcSuccessResponse<TResult>
  | JsonRpcErrorResponse<TData>;

/**
 * A JSON-RPC 2.0 notification (a request with no `id`).
 *
 * Notifications are fire-and-forget — no response is expected.
 */
export interface JsonRpcNotification<
  TMethod extends string = string,
  TParams = unknown,
> {
  readonly jsonrpc: typeof JSONRPC_VERSION;
  readonly id?: never;
  /** The notification method name. */
  readonly method: TMethod;
  /** Structured parameters for the notification. */
  readonly params: TParams;
  /**
   * Host-issued metadata for host→worker push notifications such as events.
   * Worker→host notifications echo only `paperclipInvocationId`.
   */
  readonly paperclipInvocation?: PluginInvocationContext;
  /** Opaque top-level invocation id echoed by worker→host notifications. */
  readonly paperclipInvocationId?: string;
}

/**
 * Any well-formed JSON-RPC 2.0 message (request, response, or notification).
 */
export type JsonRpcMessage =
  | JsonRpcRequest
  | JsonRpcResponse
  | JsonRpcNotification;

// ---------------------------------------------------------------------------
// Error Codes
// ---------------------------------------------------------------------------

/**
 * Standard JSON-RPC 2.0 error codes.
 *
 * @see https://www.jsonrpc.org/specification#error_object
 */
export const JSONRPC_ERROR_CODES = {
  /** Invalid JSON was received by the server. */
  PARSE_ERROR: -32700,
  /** The JSON sent is not a valid Request object. */
  INVALID_REQUEST: -32600,
  /** The method does not exist or is not available. */
  METHOD_NOT_FOUND: -32601,
  /** Invalid method parameter(s). */
  INVALID_PARAMS: -32602,
  /** Internal JSON-RPC error. */
  INTERNAL_ERROR: -32603,
} as const;

export type JsonRpcErrorCode =
  (typeof JSONRPC_ERROR_CODES)[keyof typeof JSONRPC_ERROR_CODES];

/**
 * Paperclip plugin-specific error codes.
 *
 * These live in the JSON-RPC "server error" reserved range (-32000 to -32099)
 * as specified by JSON-RPC 2.0 for implementation-defined server errors.
 *
 * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
 */
export const PLUGIN_RPC_ERROR_CODES = {
  /** The worker process is not running or not reachable. */
  WORKER_UNAVAILABLE: -32000,
  /** The plugin does not have the required capability for this operation. */
  CAPABILITY_DENIED: -32001,
  /** The worker reported an unhandled error during method execution. */
  WORKER_ERROR: -32002,
  /** The method call timed out waiting for the worker response. */
  TIMEOUT: -32003,
  /** The worker does not implement the requested optional method. */
  METHOD_NOT_IMPLEMENTED: -32004,
  /** The worker→host call attempted to escape the current invocation company scope. */
  INVOCATION_SCOPE_DENIED: -32005,
  /**
   * A `configChanged` delivery would have collapsed a single-tenant worker onto
   * a second, distinct company's configuration. The worker fails closed instead
   * of silently overwriting the already-applied tenant's config. A plugin that
   * genuinely serves multiple companies from one worker must opt in via
   * `multiCompanyConfig: true` on its definition.
   */
  CROSS_TENANT_CONFIG: -32006,
  /** A catch-all for errors that do not fit other categories. */
  UNKNOWN: -32099,
} as const;

export type PluginRpcErrorCode =
  (typeof PLUGIN_RPC_ERROR_CODES)[keyof typeof PLUGIN_RPC_ERROR_CODES];

// ---------------------------------------------------------------------------
// Invocation scope metadata
// ---------------------------------------------------------------------------

/**
 * Company scope attached by the host to one top-level plugin invocation.
 * Absence of this metadata means the invocation is instance/global scoped.
 */
export interface PluginInvocationScope {
  companyId: string;
  projectGit?: { projectId: string; workspaceId?: string; runId?: string; agentId?: string; operation?: "prepare" | "inspect" | "remove" };
}

/**
 * Opaque invocation metadata generated by the host. Workers must not derive or
 * mutate this. They only echo the id on nested worker→host RPC calls.
 */
export interface PluginInvocationContext {
  id: string;
  scope: PluginInvocationScope;
  /**
   * An optional W3C `traceparent` for the active host span. The host mints it
   * per call from the active startup span. The worker treats it as opaque: it
   * tags its provider span with it and never derives parentage from it. The host
   * mints the parentage from its own invocation record, so a worker can never
   * forge a parent.
   */
  traceparent?: string;
}

/**
 * Context provided to host-side worker→host handlers after the worker echoes a
 * host-issued invocation id.
 */
export interface WorkerHostCallContext {
  /** Host-owned aggregate timing budget; never received from the worker. */
  providerSpanBudget?: { remaining: number };
  invocationScope?: PluginInvocationScope | null;
  invalidInvocationScope?: boolean;
  /**
   * The W3C `traceparent` the host minted for the echoed invocation. The host
   * recovers it from its own invocation record, not from the worker, so a worker
   * can never forge a span parent. The span host handler validates and uses it.
   */
  traceparent?: string;
}

// ---------------------------------------------------------------------------
// Host → Worker Method Signatures (§13 Host-Worker Protocol)
// ---------------------------------------------------------------------------

/**
 * Input for the `initialize` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.1 — `initialize`
 */
export interface InitializeParams {
  /** Full plugin manifest snapshot. */
  manifest: PaperclipPluginManifestV1;
  /** Bootstrap configuration. Company-scoped config is read via `ctx.config.get(companyId)`. */
  config: Record<string, unknown>;
  /** Instance-level metadata. */
  instanceInfo: {
    /** UUID of this Paperclip instance. */
    instanceId: string;
    /** Semver version of the running Paperclip host. */
    hostVersion: string;
  };
  /** Host API version. */
  apiVersion: number;
  /** Host-derived plugin database namespace, when the manifest declares database access. */
  databaseNamespace?: string | null;
}

/**
 * Result returned by the `initialize` RPC method.
 */
export interface InitializeResult {
  /** Whether initialization succeeded. */
  ok: boolean;
  /** Optional methods the worker has implemented (e.g. "validateConfig", "onEvent"). */
  supportedMethods?: string[];
}

/**
 * Input for the `configChanged` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.4 — `configChanged`
 */
export interface ConfigChangedParams {
  /** The newly resolved company-scoped configuration. */
  config: Record<string, unknown>;
  /** Company whose plugin config changed. */
  companyId?: string | null;
}

/**
 * Input for the `validateConfig` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
 */
export interface ValidateConfigParams {
  /** The configuration to validate. */
  config: Record<string, unknown>;
}

/**
 * Input for the `onEvent` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.5 — `onEvent`
 */
export interface OnEventParams {
  /** The domain event to deliver. */
  event: PluginEvent;
}

/**
 * Input for the `runJob` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.6 — `runJob`
 */
export interface RunJobParams {
  /** Job execution context. */
  job: PluginJobContext;
}

/**
 * Input for the `getData` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.8 — `getData`
 */
export interface GetDataParams {
  /** Plugin-defined data key (e.g. `"sync-health"`). */
  key: string;
  /** Host-authorized active company scope, when this bridge call is company-scoped. */
  companyId?: string | null;
  /** Context and query parameters from the UI. */
  params: Record<string, unknown>;
  /** Optional launcher/container metadata from the host render environment. */
  renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
}

/**
 * Input for the `performAction` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.9 — `performAction`
 */
export type PluginPerformActionActorType = "user" | "agent" | "system";

export interface PluginPerformActionActorContext {
  /** Authenticated principal type resolved by the Paperclip host. */
  type: PluginPerformActionActorType;
  /** Authenticated board user id when `type === "user"`, otherwise null. */
  userId: string | null;
  /** Authenticated agent id when `type === "agent"`, otherwise null. */
  agentId: string | null;
  /** Authenticated heartbeat/run id when available. */
  runId: string | null;
  /** Company id authorized by the host bridge for this action, when applicable. */
  companyId: string | null;
}

export interface PluginPerformActionContext {
  /** Immutable authenticated actor context supplied by the host. */
  actor: Readonly<PluginPerformActionActorContext>;
  /** Convenience alias for `actor.companyId`. */
  companyId: string | null;
}

export interface PerformActionParams {
  /** Plugin-defined action key (e.g. `"resync"`). */
  key: string;
  /** Host-authorized active company scope, when this bridge call is company-scoped. */
  companyId?: string | null;
  /** Action parameters from the UI. */
  params: Record<string, unknown>;
  /** Authenticated actor context resolved by the host, never by caller params. */
  actorContext?: PluginPerformActionActorContext | null;
  /** Optional launcher/container metadata from the host render environment. */
  renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
}

/**
 * Input for the `executeTool` RPC method.
 *
 * @see PLUGIN_SPEC.md §13.10 — `executeTool`
 */
export interface ExecuteToolParams {
  /** Tool name (without plugin namespace prefix). */
  toolName: string;
  /** Parsed parameters matching the tool's declared schema. */
  parameters: unknown;
  /** Agent run context. */
  runContext: ToolRunContext;
}

export interface PluginExternalObjectUrlCandidate {
  sanitizedCanonicalUrl: string;
  sanitizedDisplayUrl: string;
  canonicalIdentityHash: string;
  canonicalIdentity: Record<string, unknown>;
  redactedMatchedText: string;
}

export interface PluginExternalObjectSourceContext {
  companyId: string;
  sourceIssueId: string;
  sourceKind: ExternalObjectMentionSourceKind;
  sourceRecordId: string | null;
  documentKey: string | null;
  propertyKey: string | null;
}

export interface DetectExternalObjectsParams {
  companyId: string;
  urls: PluginExternalObjectUrlCandidate[];
  sourceContext: PluginExternalObjectSourceContext;
}

export interface PluginExternalObjectDetection {
  urlIdentityHash: string;
  providerKey: string;
  objectType: string;
  externalId: string;
  displayKey?: string | null;
  iconKey?: string | null;
  displayTitle?: string | null;
  confidence?: ExternalObjectMentionConfidence;
}

export interface DetectExternalObjectsResult {
  detections: PluginExternalObjectDetection[];
}

export interface PluginExternalObjectRecordSnapshot {
  id: string;
  companyId: string;
  providerKey: string;
  objectType: string;
  externalId: string;
  sanitizedCanonicalUrl: string | null;
  canonicalIdentityHash: string | null;
  displayKey: string | null;
  iconKey: string | null;
  displayTitle: string | null;
  statusKey: string | null;
  statusLabel: string | null;
  statusIconKey: string | null;
  statusCategory: ExternalObjectStatusCategory;
  statusTone: ExternalObjectStatusTone;
  liveness: ExternalObjectLivenessState;
  isTerminal: boolean;
  data: Record<string, unknown>;
  remoteVersion: string | null;
  etag: string | null;
}

export interface ResolveExternalObjectParams {
  companyId: string;
  providerKey: string;
  objectType: string;
  externalId: string;
  object: PluginExternalObjectRecordSnapshot;
}

export interface PluginExternalObjectResolvedSnapshot {
  displayKey?: string | null;
  iconKey?: string | null;
  displayTitle?: string | null;
  statusKey?: string | null;
  statusLabel?: string | null;
  statusIconKey?: string | null;
  statusCategory: ExternalObjectStatusCategory;
  statusTone: ExternalObjectStatusTone;
  isTerminal?: boolean;
  data?: Record<string, unknown>;
  remoteVersion?: string | null;
  etag?: string | null;
  ttlSeconds?: number;
}

export type PluginExternalObjectResolveResult =
  | { ok: true; snapshot: PluginExternalObjectResolvedSnapshot }
  | {
      ok: false;
      liveness: Extract<ExternalObjectLivenessState, "auth_required" | "unreachable">;
      errorCode: string;
      errorMessage?: string | null;
      retryAfterSeconds?: number;
    };

export interface RefreshExternalObjectsParams {
  companyId: string;
  objects: PluginExternalObjectRecordSnapshot[];
}

export interface RefreshExternalObjectsResult {
  results: Array<{
    objectId: string;
    result: PluginExternalObjectResolveResult;
  }>;
}

export interface PluginEnvironmentDiagnostic {
  severity: "info" | "warning" | "error";
  message: string;
  code?: string;
  details?: Record<string, unknown>;
}

export interface PluginEnvironmentDriverBaseParams {
  driverKey: string;
  companyId: string;
  environmentId: string;
  issueId?: string | null;
  config: Record<string, unknown>;
}

export interface PluginEnvironmentValidateConfigParams {
  driverKey: string;
  config: Record<string, unknown>;
}

export interface PluginEnvironmentValidationResult {
  ok: boolean;
  warnings?: string[];
  errors?: string[];
  normalizedConfig?: Record<string, unknown>;
}

export interface PluginEnvironmentProbeParams extends PluginEnvironmentDriverBaseParams {}

export interface PluginEnvironmentProbeResult {
  ok: boolean;
  summary?: string;
  diagnostics?: PluginEnvironmentDiagnostic[];
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentLease {
  providerLeaseId: string | null;
  metadata?: Record<string, unknown>;
  expiresAt?: string | null;
}

/** Serializable provider result. The host adds refresh/close lifecycle methods. */
export interface PluginEnvironmentRunnerIngressEndpoint {
  kind: "authenticated_websocket";
  websocketUrl: string;
  secretHeaders: Array<{ name: string; value: string }>;
  generation: string;
}

export interface PluginEnvironmentRunnerIngressEndpointParams
  extends PluginEnvironmentDriverBaseParams {
  lease: PluginEnvironmentLease;
  port: number;
  path: string;
}

export interface PluginEnvironmentAcquireLeaseParams extends PluginEnvironmentDriverBaseParams {
  runId: string;
  creationOperationId?: string;
  /** Explicit platform probes may request a provider-owned immutable snapshot
   * identity. Supporting providers create by that ID and return snapshotIdentity
   * in lease metadata. Older providers may omit it; the host then cannot qualify
   * a mutable snapshot name. Ordinary discovery must not allocate a sandbox. */
  resolveSnapshotIdentity?: boolean;
  workspaceMode?: string;
  requestedCwd?: string;
  agentId?: string;
  executionWorkspaceId?: string | null;
  /**
   * The harness/adapter type for THIS run (the agent's adapter), so a single
   * environment can serve mixed harnesses. When omitted, the driver falls back to
   * the environment's configured default adapter. A provider that materializes a
   * per-run sandbox should use this to select the runtime image and per-run env.
   */
  adapterType?: string;
  executionWorkspaceSettings?: Record<string, unknown> | null;
  /**
   * The absolute latest time the acquired lease may stay active, as an ISO 8601
   * timestamp. A caller with an independent deadline (for example the setup-token
   * login session) sets it. A provider that materializes a sandbox must configure
   * a provider-side expiry at or before this time, and return the real provider
   * expiry in `PluginEnvironmentLease.expiresAt`. When the provider cannot bound
   * the sandbox at or before this time, it returns no expiry, so the server fails
   * closed and releases the lease. When omitted, the provider keeps its default
   * lifetime.
   */
  requestedExpiresAt?: string | null;
}

export interface PluginEnvironmentResumeLeaseParams extends PluginEnvironmentDriverBaseParams {
  /** New run authority for a retained task; omitted by legacy environment consumers. */
  runId?: string;
  providerLeaseId: string;
  leaseMetadata?: Record<string, unknown>;
}

export interface PluginEnvironmentReleaseLeaseParams extends PluginEnvironmentDriverBaseParams {
  /** Stop the exact allocation while preserving its files, regardless of its
   * ordinary release policy. A failed stop must throw, never fall back to delete. */
  resourceDisposition?: "stop_and_retain";
  /** Explicit operator cancellation: terminate active work instead of waiting
   * for command/sync activity to drain. Still requires a provider receipt. */
  cancelActiveWork?: boolean;
  providerLeaseId: string | null;
  leaseMetadata?: Record<string, unknown>;
}

/** Returned only after the provider confirms that execution has ended. A queued
 * stop request or successful local cleanup is not a termination receipt. */
export interface PluginEnvironmentTerminationReceipt {
  providerLeaseId: string;
  state: "stopped" | "destroyed";
}

export interface PluginEnvironmentDestroyLeaseParams extends PluginEnvironmentReleaseLeaseParams {}

/** Observe this exact allocation without starting, stopping or deleting it.
 * Missing resources must be distinguished from permission/transport failures. */
export interface PluginEnvironmentInspectLeaseParams extends PluginEnvironmentDriverBaseParams {
  creationOperation?: { id: string; runId: string };
  providerLeaseId: string;
  leaseMetadata?: Record<string, unknown>;
}

export interface PluginEnvironmentLeaseObservation {
  creationCleanup?: import("./environment-creation-cleanup.js").PluginEnvironmentCreationCleanup;
  providerLeaseId: string;
  state: "active" | "stopped" | "destroyed" | "unknown";
}

export interface PluginEnvironmentRealizeWorkspaceParams extends PluginEnvironmentDriverBaseParams {
  lease: PluginEnvironmentLease;
  workspace: {
    localPath?: string;
    remotePath?: string;
    mode?: string;
    metadata?: Record<string, unknown>;
  };
}

/**
 * A plugin `environmentRealizeWorkspace` handler returns only the realized cwd and provider
 * metadata. The server, not the plugin, builds the full workspace-realization record from the run
 * request and merges this cwd and metadata into it. Do not return a `workspaceRealization` record
 * here; the server owns that record, so the referenced (mentioned) project sources reach the adapter.
 */
export interface PluginEnvironmentRealizeWorkspaceResult {
  cwd: string;
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentExecuteParams extends PluginEnvironmentDriverBaseParams {
  lease: PluginEnvironmentLease;
  command: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  stdin?: string;
  timeoutMs?: number;
  /** Optional total command execution budget, in milliseconds. A session
   * provider must keep this distinct from individual observation timeouts.
   * Zero disables this deadline. Absence keeps the existing session lifetime. */
  commandTimeoutMs?: number;
  /**
   * Run this command outside the lease's persistent session.
   *
   * The host sets this flag on a command that runs before the run's agent work,
   * for example the workspace provision command. A provider that opens a
   * persistent session on the first command must NOT open the session for such a
   * command; it runs the command one-shot and leaves the session closed. The
   * session then opens on the first in-run command instead. A provider that does
   * not use a persistent session ignores this flag.
   *
   * The default (absent or `false`) keeps the session path, so a normal in-run
   * command opens and reuses the session as before.
   */
  bypassSession?: boolean;
}

export interface PluginEnvironmentExecuteResult {
  exitCode: number | null;
  signal?: string | null;
  timedOut: boolean;
  stdout: string;
  stderr: string;
  metadata?: Record<string, unknown>;
}

/**
 * A single source→target file or directory transfer within a sync operation.
 *
 * For `environmentSyncIn`, `sourcePath` is a host path and `targetPath` is a
 * sandbox path; for `environmentSyncOut` the direction is reversed. All sandbox
 * paths are POSIX. The contract is provider-agnostic: a provider may transfer a
 * directory by whatever native mechanism it prefers (bulk upload, internal tar,
 * per-file enumeration) as long as the observable result matches this mapping.
 */
export interface PluginSyncFileMapping {
  /** Absolute path of the transfer source (host for syncIn, sandbox for syncOut). */
  sourcePath: string;
  /** Absolute path of the transfer target (sandbox for syncIn, host for syncOut). */
  targetPath: string;
  /** Whether the mapping transfers a single regular file or a directory tree. */
  kind: "file" | "directory";
  /**
   * POSIX file mode to apply at the target (e.g. `0o600` for secret material).
   * The target MUST carry this mode when the transfer completes.
   *
   * For a transfer to a host target, providers MUST apply the mode with no
   * world-readable window: create the target with the mode, or apply the mode
   * before the bytes arrive at the target path. A host file sits outside the
   * sandbox boundary, so an open window shows the bytes to other host
   * processes.
   *
   * For a transfer to a sandbox target, providers MAY apply the mode after
   * they write the bytes. The sandbox is the trust boundary, so a short window
   * shows the bytes only to code that already runs in that sandbox.
   */
  mode?: number;
  /** Glob patterns to exclude when `kind` is `"directory"`. */
  exclude?: string[];
  /**
   * Symlink handling for `kind: "directory"` transfers. Falsy preserves symlinks
   * as links; `true` dereferences them to their target bytes. Mirrors tar's `-h`.
   */
  followSymlinks?: boolean;
  /**
   * Advisory read-write intent for the sandbox target. `"rw"` means the author
   * expects the agent to change the bytes at the target and keep the change.
   * `"ro"` means the target is a read-only tree. An absent value defaults to
   * `"ro"` (read-only is the safe default for an advisory signal).
   *
   * This field is advisory metadata for an optional sandbox feedback wrapper. It
   * does not change the transfer and adds no security. A provider may read it to
   * bind the read-write targets read-write under the wrapper, but the ephemeral
   * sandbox stays the only security boundary.
   */
  access?: "rw" | "ro";
  /**
   * The sandbox directory that becomes read-write when `access` is `"rw"` and a
   * post-upload command extracts `targetPath` into a different directory. A
   * workspace, git-history, or asset mapping uploads a tar archive, so its
   * `targetPath` is the staging archive under the runtime root, not the directory
   * that the extract command fills. This field names that final destination
   * directory, so a consumer records the real read-write destination, not the
   * staging parent. When absent, the read-write destination is the parent
   * directory of `targetPath`. This field is advisory and ignored when `access`
   * is not `"rw"`.
   */
  writablePath?: string;
}

/**
 * A single control command run against the sandbox after a sync operation's
 * files have landed. Ordered within {@link PluginSyncOperation.postUploadCommands}
 * and executed in array order, fail-fast (the first non-zero exit or timeout
 * aborts the operation).
 *
 * SECURITY — command origin (Stage-1 design review, condition C1). `command` is
 * a **Paperclip/adapter-authored control operation**: it may be supplied ONLY by
 * core/adapter code. No server route, issue/comment content, project/workspace
 * file content, provider-plugin callback, or arbitrary adapter config may supply
 * a raw `command` string, and any path embedded in it MUST be built by
 * adapter/core helpers from already-confined paths and shell-quoted (C3). A
 * provider MUST treat the command as **opaque**: it may execute or reject it, but
 * MUST NOT rewrite, concatenate, or append provider-decided shell fragments to
 * it.
 */
export interface PluginPostUploadCommand {
  /**
   * The opaque, adapter-authored shell command to run after upload. Executed
   * verbatim by the provider (never rewritten/concatenated). See the security
   * note above.
   */
  command: string;
  /**
   * Working directory for the command. When present, MUST be an absolute POSIX
   * path confined under the operation's allowed sandbox target root (condition
   * C2); providers re-validate it before exec. When absent, the provider
   * defaults to the resolved sync remote/runtime root — never a process default
   * cwd.
   */
  cwd?: string;
  /** Optional per-command timeout in milliseconds. */
  timeoutMs?: number;
}

/**
 * An ordered, opaque unit of work handed to a sync hook. The `operationId` is an
 * opaque, non-sensitive token authored by the orchestrator; a provider MUST NOT
 * interpret it. Operations are applied in array order.
 */
export interface PluginSyncOperation {
  operationId: string;
  files: PluginSyncFileMapping[];
  /**
   * Optional ordered control commands run after this operation's files land, in
   * array order, fail-fast. Absent means "no commands" — byte-identical to a
   * pre-contract operation. See {@link PluginPostUploadCommand} for the command
   * origin/confinement security contract (C1–C4).
   */
  postUploadCommands?: PluginPostUploadCommand[];
}

export interface PluginEnvironmentSyncInParams extends PluginEnvironmentDriverBaseParams {
  lease: PluginEnvironmentLease;
  operations: PluginSyncOperation[];
}

export interface PluginEnvironmentSyncOutParams extends PluginEnvironmentDriverBaseParams {
  lease: PluginEnvironmentLease;
  operations: PluginSyncOperation[];
}

/** Per-operation transfer accounting returned by a sync hook, for observability. */
export interface PluginEnvironmentSyncResult {
  operations: {
    operationId: string;
    filesTransferred: number;
    bytesTransferred: number;
  }[];
}

export type PluginEnvironmentInteractiveSetupStatus =
  | "starting"
  | "waiting_for_user"
  | "capturing"
  | "promoted"
  | "cancelled"
  | "timed_out"
  | "failed"
  | "missing";

export type PluginEnvironmentInteractiveSetupConnectionType =
  | "ssh"
  | (string & {});

export type PluginEnvironmentTemplateRefKind =
  | "snapshot"
  | "image"
  | "provider_template"
  | "unknown"
  | (string & {});

export interface PluginEnvironmentInteractiveSetupConnectionSummary {
  type: PluginEnvironmentInteractiveSetupConnectionType;
  username?: string | null;
  hostRedacted: boolean;
  portRedacted: boolean;
  commandRedacted?: boolean;
  expiresAt?: string | null;
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentInteractiveSetupConnectionPayload {
  type: PluginEnvironmentInteractiveSetupConnectionType;
  command?: string | null;
  token?: string | null;
  expiresAt?: string | null;
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentInteractiveSetupSession {
  providerLeaseId: string | null;
  status: PluginEnvironmentInteractiveSetupStatus;
  connectionSummary: PluginEnvironmentInteractiveSetupConnectionSummary | null;
  connectionPayload?: PluginEnvironmentInteractiveSetupConnectionPayload | null;
  expiresAt?: string | null;
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentStartInteractiveSetupParams extends PluginEnvironmentDriverBaseParams {
  sessionId: string;
  sourceTemplateRef?: string | null;
  sourceTemplateKind?: PluginEnvironmentTemplateRefKind | null;
  connectionExpiresInMinutes?: number | null;
  expiresAt?: string | null;
}

export interface PluginEnvironmentGetInteractiveSetupParams extends PluginEnvironmentDriverBaseParams {
  providerLeaseId: string | null;
  setupMetadata?: Record<string, unknown>;
  includeConnectionPayload?: boolean;
  connectionExpiresInMinutes?: number | null;
}

export interface PluginEnvironmentCaptureTemplateParams extends PluginEnvironmentDriverBaseParams {
  providerLeaseId: string | null;
  setupMetadata?: Record<string, unknown>;
  sourceTemplateRef?: string | null;
  previousTemplateRef?: string | null;
  templateLabel?: string | null;
  timeoutMs?: number | null;
}

export interface PluginEnvironmentCaptureTemplateResult {
  templateRef: string;
  templateKind: PluginEnvironmentTemplateRefKind;
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentCancelInteractiveSetupParams extends PluginEnvironmentDriverBaseParams {
  providerLeaseId: string | null;
  setupMetadata?: Record<string, unknown>;
  reason?: string | null;
}

export interface PluginEnvironmentCancelInteractiveSetupResult {
  status: Extract<PluginEnvironmentInteractiveSetupStatus, "cancelled" | "timed_out" | "failed" | "missing">;
  metadata?: Record<string, unknown>;
}

export interface PluginEnvironmentDeleteTemplateParams extends PluginEnvironmentDriverBaseParams {
  templateRef: string;
  templateKind?: PluginEnvironmentTemplateRefKind;
  metadata?: Record<string, unknown>;
  reason?: string | null;
}

export interface PluginEnvironmentDeleteTemplateResult {
  deleted: boolean;
  metadata?: Record<string, unknown>;
}

// ---------------------------------------------------------------------------
// UI launcher / modal host interaction payloads
// ---------------------------------------------------------------------------

/**
 * Bounds request issued by a plugin UI running inside a host-managed launcher
 * container such as a modal, drawer, or popover.
 */
export interface PluginModalBoundsRequest {
  /** High-level size preset requested from the host. */
  bounds: PluginLauncherBounds;
  /** Optional explicit width override in CSS pixels. */
  width?: number;
  /** Optional explicit height override in CSS pixels. */
  height?: number;
  /** Optional lower bounds for host resizing decisions. */
  minWidth?: number;
  minHeight?: number;
  /** Optional upper bounds for host resizing decisions. */
  maxWidth?: number;
  maxHeight?: number;
}

/**
 * Reason metadata supplied by host-managed close lifecycle callbacks.
 */
export interface PluginRenderCloseEvent {
  reason:
    | "escapeKey"
    | "backdrop"
    | "hostNavigation"
    | "programmatic"
    | "submit"
    | "unknown";
  nativeEvent?: unknown;
}

// ---------------------------------------------------------------------------
// Login pseudo-terminal (PTY) worker methods.
// ---------------------------------------------------------------------------
// The host drives one live Claude `setup-token` login pseudo-terminal inside a
// sandbox provider worker. The host owns the route. It mints an opaque host
// route identifier, carries that identifier in the open request, and keys the
// close on that identifier. The worker registers the terminal under the host
// route identifier and returns a worker session identifier for the output
// notification binding only. The worker never keys a close on the worker
// session identifier, so the host closes a worker-created terminal even when the
// open reply was lost and no worker session identifier arrived. The worker sends
// output and exit as notifications, never as a reply, so the host binds them by
// the worker session identifier while the route is open.

/**
 * The closed set of login command identities. The host resolves the key from the
 * trusted adapter type and carries it in the open request. The worker maps the
 * key to a compile-time command. The open request carries no command string, so a
 * caller cannot select or override the command.
 */
export type PluginLoginCommandKey = "claude" | "codex" | "grok";

/** The open request for one live login pseudo-terminal. The worker registers the terminal by `hostRouteId`. */
export interface PluginLoginPtyOpenParams {
  /** The host-owned opaque route identifier. The worker registers the terminal by it. */
  hostRouteId: string;
  /** The environment driver key, for the worker sandbox scope. It routes the worker; it confers no command authority. */
  driverKey: string;
  /** The company that owns the login session. */
  companyId: string;
  /** The environment the login session runs in. */
  environmentId: string;
  /** The provider lease the sandbox is cached under. The worker resolves the sandbox by it. */
  providerLeaseId: string;
  /**
   * The host-resolved fixed command identity. The worker maps it to a
   * compile-time command. The open request carries no command string.
   */
  loginCommandKey: PluginLoginCommandKey;
  /**
   * The server-controlled, validated session home. The shape is exact:
   * `/tmp/paperclip-adapter-login/<uuid>`. The worker revalidates the shape
   * before it touches the filesystem.
   */
  sessionHome: string;
}

/** The open reply. It returns the worker session identifier for output binding only. */
export interface PluginLoginPtyOpenResult {
  /** The worker session identifier. It binds the output and the exit notification only. */
  workerSessionId: string;
}

/** The input request. It carries the worker session identifier and the raw input bytes. */
export interface PluginLoginPtyInputParams {
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
  /** The raw input bytes to write to the terminal. */
  data: string;
}

/** The stop request. It carries the worker session identifier. */
export interface PluginLoginPtyStopParams {
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
}

/** The close request. The host route identifier is the authoritative key. */
export interface PluginLoginPtyCloseParams {
  /**
   * The host-owned opaque route identifier. This is the authoritative close key,
   * so the host closes the terminal even when no worker session identifier
   * arrived after a lost open reply.
   */
  hostRouteId: string;
  /**
   * A non-authoritative worker session identifier. The worker never keys the
   * close on it. The field is optional, so a close with only the host route
   * identifier is a valid request for this lifecycle.
   */
  workerSessionId?: string;
}

/** The close reply. It acknowledges the close and carries the same host route identifier. */
export interface PluginLoginPtyCloseResult {
  /** The close acknowledgement. It carries the same host route identifier the close sent. */
  hostRouteId: string;
}

/** The worker→host pseudo-terminal output notification parameters. Modeled on `execute.log`. */
export interface PluginLoginPtyOutputParams {
  /**
   * The host route identifier the open request carried. The worker echoes it,
   * so the host can hold more than one concurrent login pseudo-terminal per
   * worker and route each chunk to its own route.
   */
  hostRouteId: string;
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
  /** The raw terminal output bytes. */
  chunk: string;
}

/** The worker→host pseudo-terminal exit notification parameters. */
export interface PluginLoginPtyExitParams {
  /**
   * The host route identifier the open request carried. The worker echoes it,
   * so the host can hold more than one concurrent login pseudo-terminal per
   * worker and resolve the exit against its own route.
   */
  hostRouteId: string;
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
  /** The child exit code, or null when the child ended with no code. */
  exitCode: number | null;
}

/**
 * One live login pseudo-terminal session in the worker. The worker opener returns
 * it. The shape matches the sandbox provider login pseudo-terminal session,
 * so a provider passes its session with no adapter.
 */
export interface PluginLoginPtyWorkerSession {
  /** Registers the one output listener. The session streams each raw chunk in order. */
  onData(listener: (chunk: string) => void): void;
  /** Writes raw input bytes to the pseudo-terminal. */
  write(data: string): void;
  /** Resolves with the child exit code when the command ends. */
  wait(): Promise<{ exitCode: number | null }>;
  /** Stops the child process. Safe to call more than one time. */
  kill(): void;
  /** Releases the session resources. Safe to call more than one time. */
  close(): Promise<void>;
}

/** The worker→host notification method for one pseudo-terminal output chunk. */
export const LOGIN_PTY_OUTPUT_NOTIFICATION = "loginPty.output";
/** The worker→host notification method for one pseudo-terminal exit. */
export const LOGIN_PTY_EXIT_NOTIFICATION = "loginPty.exit";

// ---------------------------------------------------------------------------
// Byte-safe duplex channel wire representation.
// ---------------------------------------------------------------------------
// A JSON-RPC message travels as one line of JSON text (see `serializeMessage`
// below). JSON has no binary type, so a raw byte chunk cannot cross this hop
// unchanged. `ChannelBytesWireValue` is the one JSON-safe encoding this
// protocol uses for a duplex channel chunk: a base64 string.
//
// Every layer above this hop carries the chunk as `Uint8Array`. This includes
// the plugin context, the worker RPC host's public duplex methods, and the
// host-side plugin worker manager. Only the JSON-RPC message itself holds the
// base64 form, and only for the one hop between the host process and the
// worker process.
//
// This base64 form is not the sandbox provider channel's wire format. That
// channel carries raw bytes with no base64 armor: a live measurement of the
// provider transport proved that every byte value survives it unchanged.
//
// HTTP/2 is the preferred transport. `queue_v1` is the soft-deprecated fallback.

/** The wire-safe JSON-RPC form of one duplex channel byte chunk: a base64 string. */
export type ChannelBytesWireValue = string;

/** Encodes raw channel bytes into the wire-safe JSON-RPC representation. */
export function encodeChannelBytes(bytes: Uint8Array): ChannelBytesWireValue {
  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
}

/**
 * Decodes the wire-safe JSON-RPC representation back to raw channel bytes.
 * Returns `null` for a value that is not a well-formed base64 string, so a
 * caller on the trust boundary treats a malformed frame as a protocol error
 * instead of silently substituting the empty byte array.
 */
export function decodeChannelBytes(value: unknown): Uint8Array | null {
  if (typeof value !== "string" || value.length === 0) return null;
  // `Buffer.from(str, "base64")` silently drops an invalid character instead
  // of throwing, so re-encode the decoded bytes and compare. A well-formed
  // base64 string round-trips to itself; a malformed one does not.
  const decoded = Buffer.from(value, "base64");
  if (decoded.toString("base64") !== value) return null;
  return new Uint8Array(decoded.buffer, decoded.byteOffset, decoded.byteLength);
}

// ---------------------------------------------------------------------------
// Generic duplex channel worker methods.
// ---------------------------------------------------------------------------
// The host drives one persistent duplex channel inside a sandbox provider
// worker. The channel replaces the file transport of the sandbox callback bridge
// with one live bidirectional stream. These messages are generic. They model the
// login pseudo-terminal contract above, but they carry no login command
// allowlist. The host owns the route. It mints an opaque host route identifier,
// carries that identifier in the open request, and keys the close on that
// identifier. The worker registers the channel under the host route identifier
// and returns a worker session identifier for the data and the exit notification
// binding only. The worker never keys a close on the worker session identifier,
// so the host closes a worker-created channel even when the open reply was lost
// and no worker session identifier arrived. The worker sends data and exit as
// notifications, never as a reply, so the host binds them by the worker session
// identifier while the route is open.

/** The open request for one persistent duplex channel. The worker registers the channel by `hostRouteId`. */
export interface PluginDuplexChannelOpenParams {
  /** The host-owned opaque route identifier. The worker registers the channel by it. */
  hostRouteId: string;
  /** The environment driver key, for the worker sandbox scope. */
  driverKey: string;
  /** The company that owns the channel. */
  companyId: string;
  /** The environment the channel runs in. */
  environmentId: string;
  /** The provider lease the sandbox is cached under. The worker resolves the sandbox by it. */
  providerLeaseId: string;
  /**
   * The command argument vector the worker runs on the channel. Element 0 is the
   * program and the rest are its arguments. The worker quotes each element for the
   * shell, so a shell metacharacter in an element cannot inject a shell command.
   */
  command: readonly string[];
}

/** The open reply. It echoes the host route identifier and returns the worker session identifier. */
export interface PluginDuplexChannelOpenResult {
  /** The host route identifier the open request carried. The worker echoes it, so the host binds the exact pair. */
  hostRouteId: string;
  /** The worker session identifier. It binds the data and the exit notification only. */
  workerSessionId: string;
}

/** The write request. It carries the exact route pair and the raw input bytes. */
export interface PluginDuplexChannelWriteParams {
  /** The host route identifier the open request carried. The worker acts only on the exact live pair. */
  hostRouteId: string;
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
  /** The raw input bytes to write to the channel, in the {@link ChannelBytesWireValue} wire form. */
  data: ChannelBytesWireValue;
}

/** The stop request. It carries the exact route pair. */
export interface PluginDuplexChannelStopParams {
  /** The host route identifier the open request carried. The worker acts only on the exact live pair. */
  hostRouteId: string;
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
}

/** The close request. The host route identifier is the authoritative key. */
export interface PluginDuplexChannelCloseParams {
  /**
   * The host-owned opaque route identifier. This is the authoritative close key,
   * so the host closes the channel even when no worker session identifier arrived
   * after a lost open reply.
   */
  hostRouteId: string;
  /**
   * A non-authoritative worker session identifier. The worker never keys the
   * close on it. The field is optional, so a close with only the host route
   * identifier is a valid request for this lifecycle.
   */
  workerSessionId?: string;
}

/** The close reply. It acknowledges the close and echoes the route identifiers. */
export interface PluginDuplexChannelCloseResult {
  /** The close acknowledgement. It carries the same host route identifier the close sent. */
  hostRouteId: string;
  /**
   * The bound worker session identifier. The worker echoes it on a bound close,
   * so the host verifies the exact pair. It is absent on a pre-bind route-only
   * close, where no session bound yet.
   */
  workerSessionId?: string;
}

/** The worker→host duplex channel data notification parameters. */
export interface PluginDuplexChannelDataParams {
  /** The host route identifier the open request carried. The worker echoes it, so the host routes the exact pair. */
  hostRouteId: string;
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
  /** The raw channel output bytes, in the {@link ChannelBytesWireValue} wire form. */
  chunk: ChannelBytesWireValue;
}

/** The worker→host duplex channel exit notification parameters. */
export interface PluginDuplexChannelExitParams {
  /** The host route identifier the open request carried. The worker echoes it, so the host routes the exact pair. */
  hostRouteId: string;
  /** The worker session identifier that the open reply returned. */
  workerSessionId: string;
  /** The child exit code, or null when the child ended with no code. */
  exitCode: number | null;
  /**
   * True when the provider transport closed with no exit data, so the exit is a
   * reason-less transport close, not a process exit. Absent or false marks a real
   * process exit. The host maps a transport close to a distinct loss reason.
   */
  transportClosed?: boolean;
}

/** The worker→host notification method for one duplex channel data chunk. */
export const DUPLEX_CHANNEL_DATA_NOTIFICATION = "duplexChannel.data";
/** The worker→host notification method for one duplex channel exit. */
export const DUPLEX_CHANNEL_EXIT_NOTIFICATION = "duplexChannel.exit";

/**
 * Map of host→worker RPC method names to their `[params, result]` types.
 *
 * This type is the single source of truth for all methods the host can call
 * on a worker. Used by both the host dispatcher and the worker handler to
 * ensure type safety across the IPC boundary.
 */
export interface HostToWorkerMethods {
  /** @see PLUGIN_SPEC.md §13.1 */
  initialize: [params: InitializeParams, result: InitializeResult];
  /** @see PLUGIN_SPEC.md §13.2 */
  health: [params: Record<string, never>, result: PluginHealthDiagnostics];
  /** @see PLUGIN_SPEC.md §12.5 */
  shutdown: [params: Record<string, never>, result: void];
  prepareIdleSleep: [params: { ownerId: string; expiresAt: number }, result: { ownerId: string; expiresAt: number; backgroundWork: "none" | "present" | "unknown" }];
  releaseIdleSleep: [params: { ownerId: string }, result: void];
  /** @see PLUGIN_SPEC.md §13.3 */
  validateConfig: [params: ValidateConfigParams, result: PluginConfigValidationResult];
  /** @see PLUGIN_SPEC.md §13.4 */
  configChanged: [params: ConfigChangedParams, result: void];
  /** @see PLUGIN_SPEC.md §13.5 */
  onEvent: [params: OnEventParams, result: void];
  /** @see PLUGIN_SPEC.md §13.6 */
  runJob: [params: RunJobParams, result: void];
  /** @see PLUGIN_SPEC.md §13.7 */
  handleWebhook: [params: PluginWebhookInput, result: void];
  /** Scoped plugin API route dispatch. */
  handleApiRequest: [params: PluginApiRequestInput, result: PluginApiResponse];
  /** @see PLUGIN_SPEC.md §13.8 */
  agentLifecycle: [params: AgentLifecycleRequest, result: AgentLifecycleResult];
  resourceLifecycle: [params: ResourceLifecycleEvent, result: ResourceLifecycleResult];
  getData: [params: GetDataParams, result: unknown];
  /** @see PLUGIN_SPEC.md §13.9 */
  performAction: [params: PerformActionParams, result: unknown];
  /** @see PLUGIN_SPEC.md §13.10 */
  executeTool: [params: ExecuteToolParams, result: ToolResult];
  detectExternalObjects: [
    params: DetectExternalObjectsParams,
    result: DetectExternalObjectsResult,
  ];
  routeAiConnection: [params: AiConnectionRouterRequest, result: AiConnectionRouterResult];
  resolveExternalObject: [
    params: ResolveExternalObjectParams,
    result: PluginExternalObjectResolveResult,
  ];
  refreshExternalObjects: [
    params: RefreshExternalObjectsParams,
    result: RefreshExternalObjectsResult,
  ];
  environmentValidateConfig: [
    params: PluginEnvironmentValidateConfigParams,
    result: PluginEnvironmentValidationResult,
  ];
  workspaceOperation: [params: PluginWorkspaceParams, result: PluginWorkspaceResult];
  environmentTask: [params: PluginEnvironmentTaskParams, result: PluginEnvironmentTaskResult];
  environmentProbe: [
    params: PluginEnvironmentProbeParams,
    result: PluginEnvironmentProbeResult,
  ];
  environmentAcquireLease: [
    params: PluginEnvironmentAcquireLeaseParams,
    result: PluginEnvironmentLease,
  ];
  environmentResumeLease: [
    params: PluginEnvironmentResumeLeaseParams,
    result: PluginEnvironmentLease,
  ];
  environmentReleaseLease: [
    params: PluginEnvironmentReleaseLeaseParams,
    result: PluginEnvironmentTerminationReceipt | void,
  ];
  environmentStopLease: [
    params: PluginEnvironmentReleaseLeaseParams,
    result: PluginEnvironmentTerminationReceipt,
  ];
  environmentDestroyLease: [
    params: PluginEnvironmentDestroyLeaseParams,
    result: PluginEnvironmentTerminationReceipt | void,
  ];
  environmentInspectLease: [
    params: PluginEnvironmentInspectLeaseParams,
    result: PluginEnvironmentLeaseObservation,
  ];
  environmentRealizeWorkspace: [
    params: PluginEnvironmentRealizeWorkspaceParams,
    result: PluginEnvironmentRealizeWorkspaceResult,
  ];
  environmentExecute: [
    params: PluginEnvironmentExecuteParams,
    result: PluginEnvironmentExecuteResult,
  ];
  environmentRunnerIngressEndpoint: [
    params: PluginEnvironmentRunnerIngressEndpointParams,
    result: PluginEnvironmentRunnerIngressEndpoint,
  ];
  environmentSyncIn: [
    params: PluginEnvironmentSyncInParams,
    result: PluginEnvironmentSyncResult,
  ];
  environmentSyncOut: [
    params: PluginEnvironmentSyncOutParams,
    result: PluginEnvironmentSyncResult,
  ];
  environmentStartInteractiveSetup: [
    params: PluginEnvironmentStartInteractiveSetupParams,
    result: PluginEnvironmentInteractiveSetupSession,
  ];
  environmentGetInteractiveSetup: [
    params: PluginEnvironmentGetInteractiveSetupParams,
    result: PluginEnvironmentInteractiveSetupSession,
  ];
  environmentCaptureTemplate: [
    params: PluginEnvironmentCaptureTemplateParams,
    result: PluginEnvironmentCaptureTemplateResult,
  ];
  environmentCancelInteractiveSetup: [
    params: PluginEnvironmentCancelInteractiveSetupParams,
    result: PluginEnvironmentCancelInteractiveSetupResult,
  ];
  environmentDeleteTemplate: [
    params: PluginEnvironmentDeleteTemplateParams,
    result: PluginEnvironmentDeleteTemplateResult,
  ];
  /** Open one live login pseudo-terminal keyed by a host-owned route identifier. */
  loginPtyOpen: [
    params: PluginLoginPtyOpenParams,
    result: PluginLoginPtyOpenResult,
  ];
  /** Write delayed input to a live login pseudo-terminal, keyed by the worker session identifier. */
  loginPtyInput: [params: PluginLoginPtyInputParams, result: void];
  /** Stop a live login pseudo-terminal child, keyed by the worker session identifier. */
  loginPtyStop: [params: PluginLoginPtyStopParams, result: void];
  /** Close a live login pseudo-terminal by the host route identifier and return a bound acknowledgement. */
  loginPtyClose: [
    params: PluginLoginPtyCloseParams,
    result: PluginLoginPtyCloseResult,
  ];
  /** Open one persistent duplex channel keyed by a host-owned route identifier. */
  duplexChannelOpen: [
    params: PluginDuplexChannelOpenParams,
    result: PluginDuplexChannelOpenResult,
  ];
  /** Write raw input to a persistent duplex channel, keyed by the worker session identifier. */
  duplexChannelWrite: [params: PluginDuplexChannelWriteParams, result: void];
  /** Stop a persistent duplex channel child, keyed by the worker session identifier. */
  duplexChannelStop: [params: PluginDuplexChannelStopParams, result: void];
  /** Close a persistent duplex channel by the host route identifier and return a bound acknowledgement. */
  duplexChannelClose: [
    params: PluginDuplexChannelCloseParams,
    result: PluginDuplexChannelCloseResult,
  ];
}

/** Union of all host→worker method names. */
export type HostToWorkerMethodName = keyof HostToWorkerMethods;

/** Required methods the worker MUST implement. */
export const HOST_TO_WORKER_REQUIRED_METHODS: readonly HostToWorkerMethodName[] = [
  "initialize",
  "health",
  "shutdown",
] as const;

/** Optional methods the worker MAY implement. */
export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[] = [
  "prepareIdleSleep",
  "releaseIdleSleep",
  "validateConfig",
  "configChanged",
  "onEvent",
  "runJob",
  "handleWebhook",
  "handleApiRequest",
  "agentLifecycle",
  "resourceLifecycle",
  "workspaceOperation",
  "getData",
  "performAction",
  "executeTool",
  "detectExternalObjects",
  "routeAiConnection",
  "resolveExternalObject",
  "refreshExternalObjects",
  "environmentValidateConfig",
  "environmentTask",
  "environmentProbe",
  "environmentAcquireLease",
  "environmentResumeLease",
  "environmentReleaseLease",
  "environmentStopLease",
  "environmentDestroyLease",
  "environmentInspectLease",
  "environmentRealizeWorkspace",
  "environmentExecute",
  "environmentRunnerIngressEndpoint",
  "environmentSyncIn",
  "environmentSyncOut",
  "environmentStartInteractiveSetup",
  "environmentGetInteractiveSetup",
  "environmentCaptureTemplate",
  "environmentCancelInteractiveSetup",
  "environmentDeleteTemplate",
  "loginPtyOpen",
  "loginPtyInput",
  "loginPtyStop",
  "loginPtyClose",
  "duplexChannelOpen",
  "duplexChannelWrite",
  "duplexChannelStop",
  "duplexChannelClose",
] as const;

// ---------------------------------------------------------------------------
// Worker → Host Method Signatures (SDK client calls)
// ---------------------------------------------------------------------------

/**
 * Map of worker→host RPC method names to their `[params, result]` types.
 *
 * These represent the SDK client calls that the worker makes back to the
 * host to access platform services (state, entities, config, etc.).
 */
export interface PluginSpanRecord {
  name: string;
  /** A completed remote lifecycle is linked to its observer, never made its child. */
  relationship?: "linked";
  attributes?: Record<string, string | number | boolean>;
  status?: { code: number; message?: string };
  startTimeMs?: number;
  endTimeMs?: number;
  /** Nested timing receipts, bounded and validated again by the host. */
  children?: PluginSpanRecord[];
}

export interface WorkerToHostMethods {
  // Config
  "config.get": [params: { companyId?: string }, result: Record<string, unknown>];

  // Trusted local folders
  "localFolders.declarations": [
    params: Record<string, never>,
    result: PluginLocalFolderDeclaration[],
  ];
  "localFolders.configure": [
    params: {
      companyId: string;
      folderKey: string;
      path: string;
      access?: "read" | "readWrite";
      requiredDirectories?: string[];
      requiredFiles?: string[];
    },
    result: PluginLocalFolderStatus,
  ];
  "localFolders.status": [
    params: { companyId: string; folderKey: string },
    result: PluginLocalFolderStatus,
  ];
  "localFolders.list": [
    params: { companyId: string; folderKey: string; relativePath?: string | null; recursive?: boolean; maxEntries?: number },
    result: PluginLocalFolderListing,
  ];
  "localFolders.readText": [
    params: { companyId: string; folderKey: string; relativePath: string },
    result: string,
  ];
  "localFolders.writeTextAtomic": [
    params: {
      companyId: string;
      folderKey: string;
      relativePath: string;
      contents: string;
    },
    result: PluginLocalFolderStatus,
  ];
  "localFolders.deleteFile": [
    params: { companyId: string; folderKey: string; relativePath: string },
    result: PluginLocalFolderStatus,
  ];

  // State
  "state.get": [
    params: { scopeKind: string; scopeId?: string; namespace?: string; stateKey: string },
    result: unknown,
  ];
  "state.set": [
    params: { scopeKind: string; scopeId?: string; namespace?: string; stateKey: string; value: unknown },
    result: void,
  ];
  "state.delete": [
    params: { scopeKind: string; scopeId?: string; namespace?: string; stateKey: string },
    result: void,
  ];

  // Restricted plugin database namespace
  "db.namespace": [
    params: Record<string, never>,
    result: string,
  ];
  "db.query": [
    params: { sql: string; params?: unknown[] },
    result: unknown[],
  ];
  "db.execute": [
    params: { sql: string; params?: unknown[] },
    result: { rowCount: number },
  ];

  // Entities
  "entities.upsert": [
    params: {
      entityType: string;
      scopeKind: PluginStateScopeKind;
      scopeId?: string;
      externalId?: string;
      title?: string;
      status?: string;
      data: Record<string, unknown>;
    },
    result: {
      id: string;
      entityType: string;
      scopeKind: PluginStateScopeKind;
      scopeId: string | null;
      externalId: string | null;
      title: string | null;
      status: string | null;
      data: Record<string, unknown>;
      createdAt: string;
      updatedAt: string;
    },
  ];
  "entities.list": [
    params: {
      entityType?: string;
      scopeKind?: PluginStateScopeKind;
      scopeId?: string;
      externalId?: string;
      limit?: number;
      offset?: number;
    },
    result: Array<{
      id: string;
      entityType: string;
      scopeKind: PluginStateScopeKind;
      scopeId: string | null;
      externalId: string | null;
      title: string | null;
      status: string | null;
      data: Record<string, unknown>;
      createdAt: string;
      updatedAt: string;
    }>,
  ];

  // Events
  "events.listLifecycle": [params: { companyId: string; limit?: number; afterId?: string }, result: ResourceLifecycleEvent[]];
  "events.acknowledgeLifecycle": [params: { companyId: string; eventId: string }, result: void];
  "events.emit": [
    params: { name: string; companyId: string; payload: unknown },
    result: void,
  ];
  "events.subscribe": [
    params: { eventPattern: string; filter?: Record<string, unknown> | null },
    result: void,
  ];

  // HTTP
  "http.fetch": [
    params: { url: string; init?: Record<string, unknown> },
    result: { status: number; statusText: string; headers: Record<string, string>; body: string },
  ];

  // Secrets
  "secrets.resolve": [
    params: { secretRef: string | EnvSecretRefBinding; companyId?: string; configPath?: string },
    result: string,
  ];

  // Activity
  "activity.log": [
    params: {
      companyId: string;
      message: string;
      entityType?: string;
      entityId?: string;
      metadata?: Record<string, unknown>;
    },
    result: void,
  ];

  // Metrics
  "metrics.write": [
    params: {
      name: string;
      value: number;
      tags?: Record<string, string>;
      /** Owning tenant for `plugin_logs.company_id` (cascade-delete scope). `null`/omitted = instance-scope. */
      companyId?: string | null;
    },
    result: void,
  ];

  // Telemetry
  "telemetry.track": [
    params: { eventName: string; dimensions?: Record<string, string | number | boolean> },
    result: void,
  ];

  // Logger
  "log": [
    params: {
      level: "info" | "warn" | "error" | "debug";
      message: string;
      meta?: Record<string, unknown>;
      /** Owning tenant for `plugin_logs.company_id` (cascade-delete scope). `null`/omitted = instance-scope. */
      companyId?: string | null;
    },
    result: void,
  ];

  // Provider span sink. The worker sends a finished provider span; the host
  // re-clamps the label and the attributes at its trust boundary, mints the
  // parentage from its own invocation record, and records the span through the
  // real tracer. The worker never sends the parent `traceparent`; the host
  // recovers it from the echoed invocation id. The RPC is capability-gated.
  "span.record": [
    params: PluginSpanRecord,
    result: void,
  ];

  // Companies (read)
  "companies.list": [
    params: { limit?: number; offset?: number },
    result: Company[],
  ];
  "companies.get": [
    params: { companyId: string },
    result: Company | null,
  ];

  // Projects (read)
  "projects.list": [
    params: { companyId: string; limit?: number; offset?: number },
    result: Project[],
  ];
  "projects.resolveGitCredential": [
    params: { projectId: string; workspaceId: string; companyId: string },
    result: string | null,
  ];
  "projects.getInstanceSecrets": [
    params: { projectId: string; companyId: string },
    result: Record<string, string>,
  ];
  "projects.get": [
    params: { projectId: string; companyId: string },
    result: Project | null,
  ];
  "projects.listWorkspaces": [
    params: { projectId: string; companyId: string },
    result: PluginWorkspace[],
  ];
  "projects.getPrimaryWorkspace": [
    params: { projectId: string; companyId: string },
    result: PluginWorkspace | null,
  ];
  "projects.getWorkspaceForIssue": [
    params: { issueId: string; companyId: string },
    result: PluginWorkspace | null,
  ];
  "executionWorkspaces.get": [
    params: {
      workspaceId: string;
      companyId: string;
    },
    result: PluginExecutionWorkspaceMetadata | null,
  ];
  "projects.managed.get": [
    params: { projectKey: string; companyId: string },
    result: PluginManagedProjectResolution,
  ];
  "projects.managed.reconcile": [
    params: { projectKey: string; companyId: string },
    result: PluginManagedProjectResolution,
  ];
  "projects.managed.reset": [
    params: { projectKey: string; companyId: string },
    result: PluginManagedProjectResolution,
  ];
  "routines.managed.get": [
    params: { routineKey: string; companyId: string },
    result: PluginManagedRoutineResolution,
  ];
  "routines.managed.reconcile": [
    params: {
      routineKey: string;
      companyId: string;
      assigneeAgentId?: string | null;
      projectId?: string | null;
    },
    result: PluginManagedRoutineResolution,
  ];
  "routines.managed.reset": [
    params: {
      routineKey: string;
      companyId: string;
      assigneeAgentId?: string | null;
      projectId?: string | null;
    },
    result: PluginManagedRoutineResolution,
  ];
  "routines.managed.update": [
    params: {
      routineKey: string;
      companyId: string;
      status?: string;
    },
    result: Routine,
  ];
  "routines.managed.run": [
    params: {
      routineKey: string;
      companyId: string;
      assigneeAgentId?: string | null;
      projectId?: string | null;
    },
    result: RoutineRun,
  ];
  "skills.managed.get": [
    params: { skillKey: string; companyId: string },
    result: PluginManagedSkillResolution,
  ];
  "skills.managed.reconcile": [
    params: { skillKey: string; companyId: string },
    result: PluginManagedSkillResolution,
  ];
  "skills.managed.reset": [
    params: { skillKey: string; companyId: string },
    result: PluginManagedSkillResolution,
  ];

  // Issues
  "issues.list": [
    params: {
      companyId: string;
      projectId?: string;
      assigneeAgentId?: string;
      originKind?: string;
      originKindPrefix?: string;
      originId?: string;
      status?: string;
      includePluginOperations?: boolean;
      limit?: number;
      offset?: number;
    },
    result: Issue[],
  ];
  "issues.get": [
    params: { issueId: string; companyId: string },
    result: Issue | null,
  ];
  "issues.create": [
    params: {
      companyId: string;
      projectId?: string;
      goalId?: string;
      parentId?: string;
      inheritExecutionWorkspaceFromIssueId?: string;
      title: string;
      description?: string;
      status?: string;
      priority?: string;
      assigneeAgentId?: string;
      assigneeUserId?: string | null;
      requestDepth?: number;
      billingCode?: string | null;
      assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
      surfaceVisibility?: string | null;
      originKind?: string | null;
      originId?: string | null;
      originRunId?: string | null;
      blockedByIssueIds?: string[];
      labelIds?: string[];
      executionWorkspaceId?: string | null;
      executionWorkspacePreference?: string | null;
      executionWorkspaceSettings?: Record<string, unknown> | null;
      actorAgentId?: string | null;
      actorUserId?: string | null;
      actorRunId?: string | null;
    },
    result: Issue,
  ];
  "issues.update": [
    params: {
      issueId: string;
      patch: Record<string, unknown>;
      companyId: string;
    },
    result: Issue,
  ];
  "issues.relations.get": [
    params: { issueId: string; companyId: string },
    result: PluginIssueRelationSummary,
  ];
  "issues.relations.setBlockedBy": [
    params: {
      issueId: string;
      companyId: string;
      blockedByIssueIds: string[];
      actorAgentId?: string | null;
      actorUserId?: string | null;
      actorRunId?: string | null;
    },
    result: PluginIssueRelationSummary,
  ];
  "issues.relations.addBlockers": [
    params: {
      issueId: string;
      companyId: string;
      blockerIssueIds: string[];
      actorAgentId?: string | null;
      actorUserId?: string | null;
      actorRunId?: string | null;
    },
    result: PluginIssueRelationSummary,
  ];
  "issues.relations.removeBlockers": [
    params: {
      issueId: string;
      companyId: string;
      blockerIssueIds: string[];
      actorAgentId?: string | null;
      actorUserId?: string | null;
      actorRunId?: string | null;
    },
    result: PluginIssueRelationSummary,
  ];
  "issues.assertCheckoutOwner": [
    params: {
      issueId: string;
      companyId: string;
      actorAgentId: string;
      actorRunId: string;
    },
    result: PluginIssueCheckoutOwnership,
  ];
  "issues.getSubtree": [
    params: {
      issueId: string;
      companyId: string;
      includeRoot?: boolean;
      includeRelations?: boolean;
      includeDocuments?: boolean;
      includeActiveRuns?: boolean;
      includeAssignees?: boolean;
    },
    result: PluginIssueSubtree,
  ];
  "issues.requestWakeup": [
    params: {
      issueId: string;
      companyId: string;
      reason?: string;
      contextSource?: string;
      idempotencyKey?: string | null;
      actorAgentId?: string | null;
      actorUserId?: string | null;
      actorRunId?: string | null;
    },
    result: PluginIssueWakeupResult,
  ];
  "issues.requestWakeups": [
    params: {
      issueIds: string[];
      companyId: string;
      reason?: string;
      contextSource?: string;
      idempotencyKeyPrefix?: string | null;
      actorAgentId?: string | null;
      actorUserId?: string | null;
      actorRunId?: string | null;
    },
    result: PluginIssueWakeupBatchResult[],
  ];
  "issues.summaries.getOrchestration": [
    params: {
      issueId: string;
      companyId: string;
      includeSubtree?: boolean;
      billingCode?: string | null;
    },
    result: PluginIssueOrchestrationSummary,
  ];
  "issues.listComments": [
    params: { issueId: string; companyId: string },
    result: IssueComment[],
  ];
  "issues.createComment": [
    params: {
      issueId: string;
      body: string;
      companyId: string;
      authorAgentId?: string;
      /** Active human company member the comment is attributed to. Requires `issue.comments.create_human_attributed`. */
      actorUserId?: string;
    },
    result: IssueComment,
  ];
  "issues.createInteraction": [
    params: {
      issueId: string;
      companyId: string;
      interaction: CreateIssueThreadInteractionInput;
      authorAgentId?: string | null;
    },
    result: IssueThreadInteraction,
  ];
  "issues.listInteractions": [
    params: { issueId: string; companyId: string },
    result: IssueThreadInteraction[],
  ];
  "issues.respondInteraction": [
    params: {
      issueId: string;
      interactionId: string;
      companyId: string;
      action: "accept" | "reject";
      /**
       * Active human company member the decision is attributed to. Required —
       * resolving an interaction is a board-user action; the host re-verifies
       * active membership at apply time and never trusts this value blindly.
       */
      actorUserId?: string;
      reason?: string | null;
    },
    result: { interaction: IssueThreadInteraction; applied: boolean },
  ];
  "issues.listAttachments": [
    params: { issueId: string; companyId: string },
    result: IssueAttachment[],
  ];
  "issues.getAttachmentContent": [
    params: { attachmentId: string; companyId: string; maxBytes?: number | null },
    result: PluginIssueAttachmentContent | null,
  ];

  // Issue Documents
  "issues.documents.list": [
    params: { issueId: string; companyId: string },
    result: IssueDocumentSummary[],
  ];
  "issues.documents.get": [
    params: { issueId: string; key: string; companyId: string },
    result: IssueDocument | null,
  ];
  "issues.documents.upsert": [
    params: {
      issueId: string;
      key: string;
      body: string;
      companyId: string;
      title?: string;
      format?: string;
      changeSummary?: string;
    },
    result: IssueDocument,
  ];
  "issues.documents.delete": [
    params: { issueId: string; key: string; companyId: string },
    result: void,
  ];

  // Approvals
  "approvals.list": [
    params: { companyId: string; status?: string | null },
    result: Approval[],
  ];
  "approvals.get": [
    params: { approvalId: string; companyId: string },
    result: Approval | null,
  ];
  "approvals.decide": [
    params: {
      approvalId: string;
      companyId: string;
      action: "approve" | "reject";
      /**
       * Active human company member the decision is attributed to. Required —
       * deciding an approval is a board-user action; the host re-verifies
       * active membership at apply time and never trusts this value blindly.
       */
      actorUserId?: string;
      decisionNote?: string | null;
    },
    result: { approval: Approval; applied: boolean },
  ];

  // Agents (read)
  "agents.list": [
    params: { companyId: string; status?: string; limit?: number; offset?: number },
    result: Agent[],
  ];
  "agents.getRuntimeIdentity": [
    params: { agentId: string; companyId: string },
    result: PluginAgentRuntimeIdentity | null,
  ];
  "agents.getRuntime": [
    params: { agentId: string; companyId: string; environmentId?: string; installEnvironmentSkills?: boolean },
    result: PluginAgentRuntimeState | null,
  ];
  "agents.get": [
    params: { agentId: string; companyId: string },
    result: Agent | null,
  ];

  // Agents (write)
  "agents.pause": [
    params: { agentId: string; companyId: string },
    result: Agent,
  ];
  "agents.resume": [
    params: { agentId: string; companyId: string },
    result: Agent,
  ];
  "agents.invoke": [
    params: { agentId: string; companyId: string; prompt: string; reason?: string },
    result: { runId: string },
  ];
  "agents.managed.get": [
    params: { agentKey: string; companyId: string },
    result: PluginManagedAgentResolution,
  ];
  "agents.managed.reconcile": [
    params: { agentKey: string; companyId: string },
    result: PluginManagedAgentResolution,
  ];
  "agents.managed.reset": [
    params: { agentKey: string; companyId: string },
    result: PluginManagedAgentResolution,
  ];

  // Agent Sessions
  "agents.sessions.create": [
    params: { agentId: string; companyId: string; taskKey?: string; reason?: string },
    result: { sessionId: string; agentId: string; companyId: string; status: "active" | "closed"; createdAt: string },
  ];
  "agents.sessions.list": [
    params: { agentId: string; companyId: string },
    result: Array<{ sessionId: string; agentId: string; companyId: string; status: "active" | "closed"; createdAt: string }>,
  ];
  "agents.sessions.sendMessage": [
    params: { sessionId: string; companyId: string; prompt: string; reason?: string },
    result: { runId: string },
  ];
  "agents.sessions.close": [
    params: { sessionId: string; companyId: string },
    result: void,
  ];

  // Goals
  "goals.list": [
    params: { companyId: string; level?: string; status?: string; limit?: number; offset?: number },
    result: Goal[],
  ];
  "goals.get": [
    params: { goalId: string; companyId: string },
    result: Goal | null,
  ];
  "goals.create": [
    params: {
      companyId: string;
      title: string;
      description?: string;
      level?: string;
      status?: string;
      parentId?: string;
      ownerAgentId?: string;
    },
    result: Goal,
  ];
  "goals.update": [
    params: {
      goalId: string;
      patch: Record<string, unknown>;
      companyId: string;
    },
    result: Goal,
  ];

  // Access
  "access.members.list": [
    params: { companyId: string; includeArchived?: boolean },
    result: PluginAccessMember[],
  ];
  "access.members.get": [
    params: { memberId: string; companyId: string },
    result: PluginAccessMember | null,
  ];
  "access.members.update": [
    params: {
      memberId: string;
      companyId: string;
      patch: {
        membershipRole?: string | null;
        status?: "pending" | "active" | "suspended";
      };
    },
    result: PluginAccessMember,
  ];
  "access.invites.list": [
    params: {
      companyId: string;
      state?: "active" | "revoked" | "accepted" | "expired";
      limit?: number;
      offset?: number;
    },
    result: { invites: PluginAccessInvite[]; nextOffset: number | null },
  ];
  "access.invites.create": [
    params: {
      companyId: string;
      allowedJoinTypes?: "human" | "agent" | "both";
      humanRole?: string | null;
      defaultsPayload?: Record<string, unknown> | null;
      agentMessage?: string | null;
    },
    result: PluginAccessInvite & { token: string },
  ];
  "access.invites.revoke": [
    params: { inviteId: string; companyId: string },
    result: PluginAccessInvite,
  ];

  // Authorization
  "authorization.grants.list": [
    params: { companyId: string; principalType?: string; principalId?: string },
    result: PrincipalPermissionGrant[],
  ];
  "authorization.grants.set": [
    params: {
      companyId: string;
      principalType: string;
      principalId: string;
      grants: Array<{ permissionKey: string; scope?: Record<string, unknown> | null }>;
      grantedByUserId?: string | null;
    },
    result: PrincipalPermissionGrant[],
  ];
  "authorization.policies.summary": [
    params: { companyId: string },
    result: PluginAuthorizationPolicySummary,
  ];
  "authorization.policies.get": [
    params: { companyId: string; resourceType: "company" | "agent" | "project" | "issue"; resourceId: string },
    result: PluginAuthorizationPolicyRecord | null,
  ];
  "authorization.policies.update": [
    params: {
      companyId: string;
      resourceType: "company" | "agent" | "project" | "issue";
      resourceId: string;
      policy: Record<string, unknown> | null;
    },
    result: PluginAuthorizationPolicyRecord,
  ];
  "authorization.policies.previewAssignment": [
    params: PluginAssignmentPreviewInput,
    result: PluginAuthorizationDecisionResult,
  ];
  "authorization.policies.explainAssignment": [
    params: PluginAssignmentPreviewInput,
    result: PluginAuthorizationDecisionResult,
  ];
  "authorization.audit.search": [
    params: {
      companyId: string;
      action?: string;
      actorType?: string;
      actorId?: string;
      entityType?: string;
      entityId?: string;
      decision?: string;
      limit?: number;
      offset?: number;
    },
    result: PluginAuthorizationAuditEntry[],
  ];
}

/** Union of all worker→host method names. */
export type WorkerToHostMethodName = keyof WorkerToHostMethods;

// ---------------------------------------------------------------------------
// Worker→Host Notification Types (fire-and-forget, no response)
// ---------------------------------------------------------------------------

/**
 * Typed parameter shapes for worker→host JSON-RPC notifications.
 *
 * Notifications are fire-and-forget — the worker does not wait for a response.
 * These are used for streaming events and logging, not for request-response RPCs.
 */
export interface WorkerToHostNotifications {
  /**
   * Forward a stream event to connected SSE clients.
   *
   * Emitted by the worker for each event on a stream channel. The host
   * publishes to the PluginStreamBus, which fans out to all SSE clients
   * subscribed to the (pluginId, channel, companyId) tuple.
   *
   * The `event` payload is JSON-serializable and sent as SSE `data:`.
   * The default SSE event type is `"message"`.
   */
  "streams.emit": {
    channel: string;
    companyId: string;
    event: unknown;
  };

  /**
   * Signal that a stream channel has been opened.
   *
   * Emitted when the worker calls `ctx.streams.open(channel, companyId)`.
   * UI clients may use this to display a "connected" indicator or begin
   * buffering input. The host tracks open channels so it can emit synthetic
   * close events if the worker crashes.
   */
  "streams.open": {
    channel: string;
    companyId: string;
  };

  /**
   * Signal that a stream channel has been closed.
   *
   * Emitted when the worker calls `ctx.streams.close(channel)`, or
   * synthetically by the host when a worker process exits with channels
   * still open. UI clients should treat this as terminal and disconnect
   * the SSE connection.
   */
  "streams.close": {
    channel: string;
    companyId: string;
  };

  /**
   * Deliver one incremental output chunk of the active `environmentExecute`
   * call to the host runner log sink.
   *
   * The worker emits this notification for each new `stdout` or `stderr` chunk
   * while one execute call runs. The host reads the active invocation id from
   * the envelope field `paperclipInvocationId`, which the worker RPC host stamps
   * from the active invocation context. The host correlates the chunk to the
   * host-owned execute route for that id and delivers it to that route's
   * `onLog` callback.
   *
   * Security: the notification carries no company id on purpose. The
   * invocation-to-company binding on the host execute route is authoritative.
   * The host never reads a company id from this payload to select the route or
   * to grant access. The `chunk` is a text string, because JSON-RPC cannot
   * carry raw bytes; the host drops a chunk that is not a bounded non-empty
   * string or whose stream name is not exactly `stdout` or `stderr`.
   */
  "execute.log": {
    stream: "stdout" | "stderr";
    chunk: string;
  };
}

/** Union of all worker→host notification method names. */
export type WorkerToHostNotificationName = keyof WorkerToHostNotifications;

// ---------------------------------------------------------------------------
// Typed Request / Response Helpers
// ---------------------------------------------------------------------------

/**
 * A typed JSON-RPC request for a specific host→worker method.
 */
export type HostToWorkerRequest<M extends HostToWorkerMethodName> =
  JsonRpcRequest<M, HostToWorkerMethods[M][0]>;

/**
 * A typed JSON-RPC success response for a specific host→worker method.
 */
export type HostToWorkerResponse<M extends HostToWorkerMethodName> =
  JsonRpcSuccessResponse<HostToWorkerMethods[M][1]>;

/**
 * A typed JSON-RPC request for a specific worker→host method.
 */
export type WorkerToHostRequest<M extends WorkerToHostMethodName> =
  JsonRpcRequest<M, WorkerToHostMethods[M][0]>;

/**
 * A typed JSON-RPC success response for a specific worker→host method.
 */
export type WorkerToHostResponse<M extends WorkerToHostMethodName> =
  JsonRpcSuccessResponse<WorkerToHostMethods[M][1]>;

// ---------------------------------------------------------------------------
// Message Factory Functions
// ---------------------------------------------------------------------------

/** Counter for generating unique request IDs when no explicit ID is provided. */
let _nextId = 1;

/** Wrap around before reaching Number.MAX_SAFE_INTEGER to prevent precision loss. */
const MAX_SAFE_RPC_ID = Number.MAX_SAFE_INTEGER - 1;

/**
 * Create a JSON-RPC 2.0 request message.
 *
 * @param method - The RPC method name
 * @param params - Structured parameters
 * @param id - Optional explicit request ID (auto-generated if omitted)
 */
export function createRequest<TMethod extends string>(
  method: TMethod,
  params: unknown,
  id?: JsonRpcId,
): JsonRpcRequest<TMethod> {
  if (_nextId >= MAX_SAFE_RPC_ID) {
    _nextId = 1;
  }
  return {
    jsonrpc: JSONRPC_VERSION,
    id: id ?? _nextId++,
    method,
    params,
  };
}

/**
 * Create a JSON-RPC 2.0 success response.
 *
 * @param id - The request ID being responded to
 * @param result - The result value
 */
export function createSuccessResponse<TResult>(
  id: JsonRpcId,
  result: TResult,
): JsonRpcSuccessResponse<TResult> {
  return {
    jsonrpc: JSONRPC_VERSION,
    id,
    result,
  };
}

/**
 * Create a JSON-RPC 2.0 error response.
 *
 * @param id - The request ID being responded to (null if the request ID could not be determined)
 * @param code - Machine-readable error code
 * @param message - Human-readable error message
 * @param data - Optional structured error data
 */
export function createErrorResponse<TData = unknown>(
  id: JsonRpcId | null,
  code: number,
  message: string,
  data?: TData,
): JsonRpcErrorResponse<TData> {
  const response: JsonRpcErrorResponse<TData> = {
    jsonrpc: JSONRPC_VERSION,
    id,
    error: data !== undefined
      ? { code, message, data }
      : { code, message } as JsonRpcError<TData>,
  };
  return response;
}

/**
 * Create a JSON-RPC 2.0 notification (fire-and-forget, no response expected).
 *
 * @param method - The notification method name
 * @param params - Structured parameters
 */
export function createNotification<TMethod extends string>(
  method: TMethod,
  params: unknown,
): JsonRpcNotification<TMethod> {
  return {
    jsonrpc: JSONRPC_VERSION,
    method,
    params,
  };
}

// ---------------------------------------------------------------------------
// Type Guards
// ---------------------------------------------------------------------------

/**
 * Check whether a value is a well-formed JSON-RPC 2.0 request.
 *
 * A request has `jsonrpc: "2.0"`, a string `method`, and an `id`.
 */
export function isJsonRpcRequest(value: unknown): value is JsonRpcRequest {
  if (typeof value !== "object" || value === null) return false;
  const obj = value as Record<string, unknown>;
  return (
    obj.jsonrpc === JSONRPC_VERSION &&
    typeof obj.method === "string" &&
    "id" in obj &&
    obj.id !== undefined &&
    obj.id !== null
  );
}

/**
 * Check whether a value is a well-formed JSON-RPC 2.0 notification.
 *
 * A notification has `jsonrpc: "2.0"`, a string `method`, but no `id`.
 */
export function isJsonRpcNotification(
  value: unknown,
): value is JsonRpcNotification {
  if (typeof value !== "object" || value === null) return false;
  const obj = value as Record<string, unknown>;
  return (
    obj.jsonrpc === JSONRPC_VERSION &&
    typeof obj.method === "string" &&
    !("id" in obj)
  );
}

/**
 * Check whether a value is a well-formed JSON-RPC 2.0 response (success or error).
 */
export function isJsonRpcResponse(value: unknown): value is JsonRpcResponse {
  if (typeof value !== "object" || value === null) return false;
  const obj = value as Record<string, unknown>;
  return (
    obj.jsonrpc === JSONRPC_VERSION &&
    "id" in obj &&
    ("result" in obj || "error" in obj)
  );
}

/**
 * Check whether a JSON-RPC response is a success response.
 */
export function isJsonRpcSuccessResponse(
  response: JsonRpcResponse,
): response is JsonRpcSuccessResponse {
  return "result" in response && !("error" in response && response.error !== undefined);
}

/**
 * Check whether a JSON-RPC response is an error response.
 */
export function isJsonRpcErrorResponse(
  response: JsonRpcResponse,
): response is JsonRpcErrorResponse {
  return "error" in response && response.error !== undefined;
}

// ---------------------------------------------------------------------------
// Serialization Helpers
// ---------------------------------------------------------------------------

/**
 * Line delimiter for JSON-RPC messages over stdio.
 *
 * Each message is a single line of JSON terminated by a newline character.
 * This follows the newline-delimited JSON (NDJSON) convention.
 */
export const MESSAGE_DELIMITER = "\n" as const;

/**
 * Serialize a JSON-RPC message to a newline-delimited string for transmission
 * over stdio.
 *
 * @param message - Any JSON-RPC message (request, response, or notification)
 * @returns The JSON string terminated with a newline
 */
export function serializeMessage(message: JsonRpcMessage): string {
  return JSON.stringify(message) + MESSAGE_DELIMITER;
}

/**
 * Parse a JSON string into a JSON-RPC message.
 *
 * Returns the parsed message or throws a `JsonRpcParseError` if the input
 * is not valid JSON or does not conform to the JSON-RPC 2.0 structure.
 *
 * @param line - A single line of JSON text (with or without trailing newline)
 * @returns The parsed JSON-RPC message
 * @throws {JsonRpcParseError} If parsing fails
 */
export function parseMessage(line: string): JsonRpcMessage {
  const trimmed = line.trim();
  if (trimmed.length === 0) {
    throw new JsonRpcParseError("Empty message");
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(trimmed);
  } catch {
    throw new JsonRpcParseError(`Invalid JSON: ${trimmed.slice(0, 200)}`);
  }

  if (typeof parsed !== "object" || parsed === null) {
    throw new JsonRpcParseError("Message must be a JSON object");
  }

  const obj = parsed as Record<string, unknown>;

  if (obj.jsonrpc !== JSONRPC_VERSION) {
    throw new JsonRpcParseError(
      `Invalid or missing jsonrpc version (expected "${JSONRPC_VERSION}", got ${JSON.stringify(obj.jsonrpc)})`,
    );
  }

  // It's a valid JSON-RPC 2.0 envelope — return as-is and let the caller
  // use the type guards for more specific classification.
  return parsed as JsonRpcMessage;
}

// ---------------------------------------------------------------------------
// Error Classes
// ---------------------------------------------------------------------------

/**
 * Error thrown when a JSON-RPC message cannot be parsed.
 */
export class JsonRpcParseError extends Error {
  override readonly name = "JsonRpcParseError";
  constructor(message: string) {
    super(message);
  }
}

/**
 * Error thrown when a JSON-RPC call fails with a structured error response.
 *
 * Captures the full `JsonRpcError` so callers can inspect the code and data.
 */
export class JsonRpcCallError extends Error {
  override readonly name = "JsonRpcCallError";
  /** The JSON-RPC error code. */
  readonly code: number;
  /** Optional structured error data from the response. */
  readonly data: unknown;

  constructor(error: JsonRpcError) {
    super(error.message);
    this.code = error.code;
    this.data = error.data;
  }
}

// ---------------------------------------------------------------------------
// Reset helper (testing only)
// ---------------------------------------------------------------------------

/**
 * Reset the internal request ID counter. **For testing only.**
 *
 * @internal
 */
export function _resetIdCounter(): void {
  _nextId = 1;
}