@h-rig/contracts 0.0.6-alpha.16 → 0.0.6-alpha.161

package/dist/src/task-data.d.ts

@@ -0,0 +1,239 @@
+/**
+ * The TASK-DATA capability seam.
+ *
+ * Floor-neutral vocab + a single `CapabilityId<TaskDataService>` describing the
+ * task-DATA reads and task-command behaviours the lifecycle, scheduler,
+ * isolation provisioning, repos, workspace, and CLI surfaces consume. The
+ * READ/normalize/validate POLICY behind each method (synchronize task-config,
+ * strip metadata, tracker projection, validator dispatch, artifact IO) is owned
+ * by `@rig/task-sources-plugin`, which `defineCapability(TASK_DATA_SERVICE_CAPABILITY).provide`s
+ * the impl. Consumers `resolve`/`require` it off a built plugin host (or read the
+ * boot-installed singleton) WITHOUT importing the provider plugin — this is the
+ * seam that replaces the cross-plugin `import("@rig/task-sources-plugin/...")`
+ * impl imports (SEAM-ONLY §6.4).
+ *
+ * Pure: types + one branded id, no behaviour.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { TaskConfigEntry, TaskRecord, RegisteredTaskSource, TaskSourceUpdate } from "./task-source";
+import type { TaskRecordReader } from "./isolation";
+import type { RuntimeInstructionProvider } from "./provider-instructions";
+import type { CanonicalTaskLifecycleStatus, TaskStateMetadataEnvelope } from "./task-state-metadata";
+/** Result of a bounded artifact-file read (preview + truncation metadata). */
+export type TaskArtifactReadResult = {
+    path: string;
+    sizeBytes: number;
+    contents: string;
+    truncated: boolean;
+    maxBytes: number;
+};
+/** One validation category outcome inside a {@link TaskValidationSummary}. */
+export type TaskValidationCategoryResult = {
+    category: string;
+    status: "pass" | "fail";
+    exit_code?: number;
+    duration_seconds: number;
+};
+/**
+ * The aggregate task-validation outcome a task closeout reads/accepts (the
+ * category-rollup shape written to `validation-summary.json` by `taskValidate`).
+ * Distinct from the schema-typed run-level `ValidationSummary` in `./validation`.
+ */
+export type TaskValidationSummary = {
+    status: "pass" | "fail" | "skipped";
+    total: number;
+    passed: number;
+    failed: number;
+    categories: TaskValidationCategoryResult[];
+};
+/** A `bd-`/source-id lifecycle status projected from the synced tracker. */
+export type SyncedTrackerStatus = CanonicalTaskLifecycleStatus | "unknown";
+export type SyncedTrackerDependency = {
+    issueId: string | null;
+    dependsOnId: string | null;
+    id?: string | null;
+    type: string | null;
+};
+export type SyncedTrackerIssue = {
+    id: string;
+    title: string | null;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    issueType: string | null;
+    status: SyncedTrackerStatus;
+    rawStatus: string | null;
+    priority: number | null;
+    dependencies: SyncedTrackerDependency[];
+};
+export type SyncedTrackerSnapshot = {
+    source: "remote" | "local";
+    baseOid: string | null;
+    issues: SyncedTrackerIssue[];
+    taskState: TaskStateMetadataEnvelope;
+};
+/** Optional fallback toggle for synced-tracker reads. */
+export type ReadSyncedTrackerOptions = {
+    allowLocalFallback?: boolean;
+};
+/** Result of resolving a single task through the configured task source. */
+export type TaskSourceTaskReadResult = {
+    configured: boolean;
+    sourceKind: string | null;
+    task: TaskRecord | null;
+};
+/** Summary of a `task reopen` operation. */
+export type TaskReopenSummary = {
+    mode: "all" | "single";
+    requestedTaskId: string | null;
+    dryRun: boolean;
+    closedFound: number;
+    reopened: string[];
+    failed: string[];
+    skipped: string[];
+};
+/** Identity fields used to resolve a task's source issue. */
+export type SourceTaskIdentity = {
+    id?: unknown;
+    sourceIssueId?: unknown;
+    source_issue_id?: unknown;
+};
+/** Result of pushing a task lifecycle update through the configured source. */
+export type TaskSourceLifecycleUpdateResult = {
+    taskId: string;
+    updated: boolean;
+    source: "plugin" | "compat" | "none" | "server";
+    sourceKind: string | null;
+    status: unknown;
+    projectSync?: unknown;
+};
+/** Input for rendering a task-run lifecycle status comment. */
+export type TaskRunLifecycleCommentInput = {
+    runId: string;
+    status: string;
+    summary: string;
+    runtimeWorkspace?: string | null;
+    logsDir?: string | null;
+    sessionDir?: string | null;
+    errorText?: string | null;
+};
+/** Boundary subset of the source-aware task-config reader options. */
+export type SourceAwareTaskConfigReadOptions = {
+    configPath?: string;
+    allowLocalTaskConfigStatusFallback?: boolean;
+};
+/**
+ * The lifecycle status values a run reflects to the task source.
+ * Mirrors the type defined in @rig/task-sources-plugin/source-lifecycle —
+ * lives here so @rig/run-exec can use it through the TaskDataService seam
+ * without a cross-plugin impl import.
+ */
+export type RunTaskSourceLifecycleStatus = "running" | "under_review" | "ci_fixing" | "merging" | "closed" | "cancelled" | "needs_attention";
+/**
+ * The run identity fields passed when reflecting a run lifecycle event to the
+ * task source.
+ */
+export type RunTaskSourceLifecycleRun = {
+    runId?: string | null;
+    taskId?: string | null;
+    sourceTask?: unknown;
+    worktreePath?: string | null;
+    logRoot?: string | null;
+    sessionPath?: string | null;
+    errorText?: string | null;
+};
+/** Optional overrides for a run lifecycle update. */
+export type RunTaskSourceLifecycleOptions = {
+    errorText?: string | null;
+};
+/** Context for building a plugin-backed task-record reader. */
+export type PluginTaskRecordReaderContext = {
+    taskSourceRegistry: {
+        list(): readonly RegisteredTaskSource[];
+        resolveById(id: string): RegisteredTaskSource;
+        resolveByKind(kind: string): RegisteredTaskSource;
+    };
+};
+/** Options selecting a source for a plugin-backed task-record reader. */
+export type PluginTaskRecordReaderOptions = {
+    projectRoot: string;
+    sourceId?: string;
+    sourceKind?: string;
+};
+/**
+ * The task-DATA service contributed by `@rig/task-sources-plugin`. Every method
+ * is keyed by `projectRoot` (the service is stateless), so it is safe to install
+ * as a boot singleton and read synchronously by substrate consumers.
+ */
+export interface TaskDataService {
+    currentTaskId(projectRoot: string): string;
+    readTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    readSourceTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    lookupTask(projectRoot: string, input: string): string;
+    artifactDirForId(projectRoot: string, id: string): string;
+    taskInfo(projectRoot: string, taskId?: string, runtimeProviderOverride?: RuntimeInstructionProvider): Promise<void>;
+    taskDeps(projectRoot: string, taskId?: string): Promise<void>;
+    taskStatus(projectRoot: string): void;
+    taskScope(projectRoot: string, expandFiles: boolean, taskId?: string): Promise<void>;
+    taskReady(projectRoot: string): Promise<void>;
+    taskLookup(projectRoot: string, id: string): string;
+    taskRecord(projectRoot: string, type: "decision" | "failure", text: string, taskId?: string): void;
+    taskReopen(projectRoot: string, options: {
+        all: boolean;
+        taskId?: string;
+        dryRun?: boolean;
+    }): TaskReopenSummary;
+    taskValidate(projectRoot: string, taskId?: string, validatorRegistry?: unknown): Promise<boolean>;
+    taskArtifacts(projectRoot: string, taskId?: string): void;
+    taskArtifactDir(projectRoot: string, taskId?: string): string;
+    taskArtifactWrite(projectRoot: string, filename: string, content: string, taskId?: string): void;
+    taskArtifactRead(projectRoot: string, filename: string, options?: {
+        taskId?: string;
+        maxBytes?: number;
+    }): TaskArtifactReadResult;
+    taskDependencyIds(projectRoot: string, taskId: string): string[];
+    changedFilesForTask(projectRoot: string, taskId: string, scoped: boolean): string[];
+    pendingFilesForTask(projectRoot: string, taskId: string, scoped: boolean): string[];
+    readSourceAwareTaskStatus(projectRoot: string, taskId: string, options?: SourceAwareTaskConfigReadOptions): Promise<unknown>;
+    readConfiguredTaskSourceTask(projectRoot: string, taskId: string): Promise<TaskSourceTaskReadResult>;
+    updateConfiguredTaskSourceTask(projectRoot: string, input: {
+        taskId: string;
+        sourceTask?: SourceTaskIdentity | null;
+        update: TaskSourceUpdate;
+    }): Promise<TaskSourceLifecycleUpdateResult>;
+    buildTaskRunLifecycleComment(input: TaskRunLifecycleCommentInput): string;
+    /**
+     * Compat fallback: push an update to a github-issues-backed task by parsing
+     * its `owner/repo#n` source-issue id. Returns false when the id does not match
+     * the taskId. Exposed on the seam so the kernel agent-launch executor can apply
+     * the source-aware compatibility update without importing the provider plugin.
+     */
+    updateGithubIssueTaskBySourceIssueId(sourceIssueId: string | null | undefined, taskId: string, update: TaskSourceUpdate): boolean;
+    /**
+     * Compat fallback: push a status/comment update through the source-aware
+     * task-config (github-issues, files, or legacy task-config). Returns false when
+     * no writable source is configured. Seam-exposed for the kernel executor.
+     */
+    updateSourceAwareTaskConfigTask(projectRoot: string, taskId: string, update: TaskSourceUpdate): boolean;
+    /**
+     * Reflect a run lifecycle event (start/stop/closeout) to the configured task
+     * source. Returns null when no taskId is present or no source is configured.
+     * Exposed on the seam so @rig/run-exec can call it without importing
+     * @rig/task-sources-plugin impl files directly (SEAM-ONLY §6.4).
+     */
+    updateRunTaskSourceLifecycle(projectRoot: string, run: RunTaskSourceLifecycleRun, status: RunTaskSourceLifecycleStatus, summary: string, options?: RunTaskSourceLifecycleOptions): Promise<TaskSourceLifecycleUpdateResult | null>;
+    createLegacyTaskConfigRecordReader(projectRoot: string, options?: {
+        configPath?: string;
+    }): TaskRecordReader;
+    createSourceAwareTaskConfigRecordReader(projectRoot: string, options?: SourceAwareTaskConfigReadOptions): TaskRecordReader;
+    createPluginTaskRecordReader(context: PluginTaskRecordReaderContext, options: PluginTaskRecordReaderOptions): TaskRecordReader;
+    readSyncedTrackerState(projectRoot: string, deps?: unknown, options?: ReadSyncedTrackerOptions): SyncedTrackerSnapshot;
+    listReadyTaskIdsFromTracker(snapshot: SyncedTrackerSnapshot): string[];
+    normalizeTaskLifecycleStatus(status: unknown): CanonicalTaskLifecycleStatus | null;
+}
+/** Stable id string for the task-data service capability. */
+export declare const TASK_DATA_SERVICE_CAPABILITY_ID = "task-sources.task-data";
+/**
+ * The branded task-data capability id. `defineCapability(TASK_DATA_SERVICE_CAPABILITY)`
+ * (provider and consumers, independently) resolves to a `TaskDataService`.
+ */
+export declare const TASK_DATA_SERVICE_CAPABILITY: CapabilityId<TaskDataService>;

package/dist/src/task-data.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-data.ts
+var TASK_DATA_SERVICE_CAPABILITY_ID = "task-sources.task-data";
+var TASK_DATA_SERVICE_CAPABILITY = makeCapabilityId(TASK_DATA_SERVICE_CAPABILITY_ID);
+export {
+  TASK_DATA_SERVICE_CAPABILITY_ID,
+  TASK_DATA_SERVICE_CAPABILITY
+};

package/dist/src/task-graph-primitives.d.ts

@@ -0,0 +1,47 @@
+import type { TaskSummary } from "./graph";
+export type TaskDependencyProjection = Pick<TaskSummary, "id" | "status" | "priority" | "metadata"> & Partial<Pick<TaskSummary, "externalId" | "sourceIssueId" | "dependencies" | "parentChildDeps" | "createdAt" | "updatedAt" | "role" | "scope" | "validationKeys">> & {
+    readonly title?: string | null;
+};
+export type ClientTaskProjection = TaskDependencyProjection & {
+    readonly title?: string | null;
+    readonly assignees?: readonly string[] | null;
+    readonly assignedTo?: string | readonly string[] | null;
+    readonly labels?: readonly string[] | null;
+};
+export type TaskProjectionInput = {
+    readonly id: string;
+    readonly title?: string | null;
+    readonly status?: string | null;
+    readonly source?: string | null;
+    readonly url?: string | null;
+    readonly body?: string | null;
+    readonly priority?: number | string | null;
+    readonly assignedTo?: string | readonly string[] | null;
+    readonly assignees?: readonly string[] | null;
+    readonly dependencies?: readonly string[] | null;
+    readonly parentChildDeps?: readonly string[] | null;
+    readonly metadata?: Record<string, unknown> | null;
+    readonly [key: string]: unknown;
+};
+export type TaskDependencyBadgeKind = "blocked" | "ready" | "dependency";
+export interface TaskDependencyBadge {
+    readonly kind: TaskDependencyBadgeKind;
+    readonly label: string;
+    readonly description: string;
+    readonly count?: number;
+    readonly taskIds?: readonly string[];
+}
+export interface TaskDependencyBadgeSummary {
+    readonly taskId: string;
+    readonly blockingDepth: number;
+    readonly dependencyIds: readonly string[];
+    readonly unresolvedDependencyRefs: readonly string[];
+    readonly blockedBy: readonly string[];
+    readonly blocks: readonly string[];
+    readonly blocked: boolean;
+    readonly ready: boolean;
+    readonly dependencyCount: number;
+    readonly dependentCount: number;
+    readonly badges: readonly TaskDependencyBadge[];
+}
+export type TaskScopeInput = readonly string[] | TaskDependencyProjection;

package/dist/src/task-graph-primitives.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/task-source.d.ts

@@ -0,0 +1,102 @@
+import type { CapabilityId } from "./capability-id";
+import type { TaskSourceRegistration } from "./plugin";
+import type { TaskBrowserConfig } from "./browser";
+/**
+ * A single entry in the on-disk task-config map (`.rig/task-config.json`).
+ * Floor-neutral DATA shape. The READ/normalize POLICY (synchronize, strip
+ * metadata, validation-description extraction) is owned by
+ * @rig/task-sources-plugin (`task-state`), NOT the floor.
+ */
+export type TaskConfigEntry = {
+    title?: string;
+    status?: string;
+    role?: string;
+    description?: string;
+    acceptance_criteria?: string;
+    scope?: string[];
+    validation?: string[];
+    browser?: TaskBrowserConfig;
+    repo_pins?: Record<string, string>;
+    criticality?: "core" | "high" | "normal";
+    queue_weight?: number;
+    creates_repo?: boolean;
+    auto_synced?: boolean;
+};
+/**
+ * A single task record returned by a task source adapter.
+ * Open-ended to allow adapters to include source-specific fields.
+ */
+export interface TaskRecord {
+    id: string;
+    deps: readonly string[];
+    status: "ready" | "in_progress" | "closed" | "blocked" | "open" | string;
+    [extra: string]: unknown;
+}
+/**
+ * The NORMALIZED, surface-facing task shape (the projection consumers read).
+ * The TYPE is floor-neutral vocab and lives here in contracts; the
+ * normalization POLICY that produces it (field-mapping a raw `TaskRecord` into
+ * this shape — title/body/url/dependency fallback chains) is owned by
+ * @rig/task-sources-plugin (`toRigTask`), NOT by the floor.
+ */
+export type RigTask = {
+    readonly id: string;
+    readonly title?: string | null;
+    readonly status?: string | null;
+    readonly source?: string | null;
+    readonly url?: string | null;
+    readonly body?: string | null;
+    readonly priority?: number | string | null;
+    readonly assignedTo?: string | readonly string[] | null;
+    readonly assignees?: readonly string[] | null;
+    readonly dependencies?: readonly string[] | null;
+    readonly parentChildDeps?: readonly string[] | null;
+    readonly metadata?: Record<string, unknown> | null;
+    readonly [key: string]: unknown;
+};
+/** Alias retained for call sites that accept any task-like projection. */
+export type TaskLike = RigTask;
+/**
+ * A registered task source adapter — combines the plugin-level registration
+ * metadata with the runtime-callable interface.
+ */
+export interface TaskSourceUpdate {
+    status?: TaskRecord["status"];
+    title?: string;
+    body?: string;
+    comment?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskSourceCreateInput {
+    title: string;
+    body: string;
+    deps?: readonly string[];
+    parents?: readonly string[];
+    metadata?: Record<string, unknown>;
+}
+export type TaskSourceCreateResult = TaskRecord;
+export interface RegisteredTaskSource extends TaskSourceRegistration {
+    list(): Promise<readonly TaskRecord[]>;
+    get?(id: string): Promise<TaskRecord | undefined>;
+    updateStatus?(id: string, status: TaskRecord["status"]): Promise<void>;
+    updateTask?(id: string, update: TaskSourceUpdate): Promise<void>;
+    create?(input: TaskSourceCreateInput): Promise<TaskSourceCreateResult>;
+}
+export type TaskIoCreateResult = {
+    readonly taskId: string | null;
+    readonly source: string;
+    readonly result: unknown;
+};
+/**
+ * Source-owned task IO projection seam. Providers normalize raw task-source
+ * records into RigTask and adapt generic task creation payloads to the
+ * configured source; consumers resolve this instead of importing @rig/core
+ * task-source glue.
+ */
+export interface TaskIoService {
+    listTasks(projectRoot: string): Promise<readonly RigTask[]>;
+    getTask(projectRoot: string, taskId: string): Promise<RigTask | null>;
+    createTask(projectRoot: string, task: Record<string, unknown>): Promise<TaskIoCreateResult>;
+}
+export declare const TASK_IO_SERVICE_CAPABILITY_ID = "task-sources.task-io";
+export declare const TASK_IO_SERVICE_CAPABILITY: CapabilityId<TaskIoService>;

package/dist/src/task-source.js

@@ -1 +1,13 @@
 // @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-source.ts
+var TASK_IO_SERVICE_CAPABILITY_ID = "task-sources.task-io";
+var TASK_IO_SERVICE_CAPABILITY = makeCapabilityId(TASK_IO_SERVICE_CAPABILITY_ID);
+export {
+  TASK_IO_SERVICE_CAPABILITY_ID,
+  TASK_IO_SERVICE_CAPABILITY
+};

package/dist/src/task-state-metadata.d.ts

@@ -0,0 +1,21 @@
+export type CanonicalTaskLifecycleStatus = "draft" | "open" | "ready" | "queued" | "in_progress" | "under_review" | "blocked" | "completed" | "cancelled";
+export type TaskStateMetadata = {
+    claimId?: string;
+    status: CanonicalTaskLifecycleStatus;
+    ownerId?: string;
+    claimedAt?: string;
+    lastEvidenceAt?: string;
+    runId?: string;
+    branchName?: string;
+    prNumber?: number;
+    prUrl?: string;
+    reviewState?: string;
+    blockerReason?: string;
+    sourceCommit?: string;
+};
+export type TaskStateMetadataEnvelope = {
+    schemaVersion: number;
+    supported: boolean;
+    baseTrackerCommit: string | null;
+    tasks: Record<string, TaskStateMetadata>;
+};

package/dist/src/task-state-metadata.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/terminal.d.ts

@@ -0,0 +1,130 @@
+import { Schema } from "effect";
+export declare const DEFAULT_TERMINAL_ID = "default";
+export declare const TerminalThreadInput: Schema.Struct<{
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalThreadInput = Schema.Codec.Encoded<typeof TerminalThreadInput>;
+declare const TerminalSessionInput: Schema.Struct<{
+    readonly terminalId: Schema.withDecodingDefault<Schema.Trim>;
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalSessionInput = Schema.Codec.Encoded<typeof TerminalSessionInput>;
+export declare const TerminalOpenInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly cols: Schema.optional<Schema.Int>;
+    readonly rows: Schema.optional<Schema.Int>;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly terminalId: Schema.withDecodingDefault<Schema.Trim>;
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalOpenInput = Schema.Codec.Encoded<typeof TerminalOpenInput>;
+export declare const TerminalWriteInput: Schema.Struct<{
+    readonly data: Schema.String;
+    readonly terminalId: Schema.withDecodingDefault<Schema.Trim>;
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalWriteInput = Schema.Codec.Encoded<typeof TerminalWriteInput>;
+export declare const TerminalResizeInput: Schema.Struct<{
+    readonly cols: Schema.Int;
+    readonly rows: Schema.Int;
+    readonly terminalId: Schema.withDecodingDefault<Schema.Trim>;
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalResizeInput = Schema.Codec.Encoded<typeof TerminalResizeInput>;
+export declare const TerminalClearInput: Schema.Struct<{
+    readonly terminalId: Schema.withDecodingDefault<Schema.Trim>;
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalClearInput = Schema.Codec.Encoded<typeof TerminalClearInput>;
+export declare const TerminalRestartInput: Schema.Struct<{
+    readonly cwd: Schema.Trim;
+    readonly cols: Schema.Int;
+    readonly rows: Schema.Int;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly threadId: Schema.Trim;
+}>;
+export declare const TerminalCloseInput: Schema.Struct<{
+    readonly terminalId: Schema.optional<Schema.Trim>;
+    readonly deleteHistory: Schema.optional<Schema.Boolean>;
+    readonly threadId: Schema.Trim;
+}>;
+export type TerminalCloseInput = Schema.Codec.Encoded<typeof TerminalCloseInput>;
+export declare const TerminalSessionStatus: Schema.Literals<readonly ["starting", "running", "exited", "error"]>;
+export type TerminalSessionStatus = typeof TerminalSessionStatus.Type;
+export declare const TerminalSessionSnapshot: Schema.Struct<{
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly cwd: Schema.String;
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "error"]>;
+    readonly pid: Schema.NullOr<Schema.Int>;
+    readonly history: Schema.String;
+    readonly exitCode: Schema.NullOr<Schema.Int>;
+    readonly exitSignal: Schema.NullOr<Schema.String>;
+    readonly updatedAt: Schema.String;
+}>;
+export type TerminalSessionSnapshot = typeof TerminalSessionSnapshot.Type;
+export declare const TerminalEvent: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"started">;
+    readonly snapshot: Schema.Struct<{
+        readonly threadId: Schema.String;
+        readonly terminalId: Schema.String;
+        readonly cwd: Schema.String;
+        readonly status: Schema.Literals<readonly ["starting", "running", "exited", "error"]>;
+        readonly pid: Schema.NullOr<Schema.Int>;
+        readonly history: Schema.String;
+        readonly exitCode: Schema.NullOr<Schema.Int>;
+        readonly exitSignal: Schema.NullOr<Schema.String>;
+        readonly updatedAt: Schema.String;
+    }>;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"output">;
+    readonly data: Schema.String;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"exited">;
+    readonly exitCode: Schema.NullOr<Schema.Int>;
+    readonly exitSignal: Schema.NullOr<Schema.String>;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"error">;
+    readonly message: Schema.String;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"cleared">;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"restarted">;
+    readonly snapshot: Schema.Struct<{
+        readonly threadId: Schema.String;
+        readonly terminalId: Schema.String;
+        readonly cwd: Schema.String;
+        readonly status: Schema.Literals<readonly ["starting", "running", "exited", "error"]>;
+        readonly pid: Schema.NullOr<Schema.Int>;
+        readonly history: Schema.String;
+        readonly exitCode: Schema.NullOr<Schema.Int>;
+        readonly exitSignal: Schema.NullOr<Schema.String>;
+        readonly updatedAt: Schema.String;
+    }>;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"activity">;
+    readonly hasRunningSubprocess: Schema.Boolean;
+    readonly threadId: Schema.String;
+    readonly terminalId: Schema.String;
+    readonly createdAt: Schema.String;
+}>]>;
+export type TerminalEvent = typeof TerminalEvent.Type;
+export {};

package/dist/src/terminal.js

@@ -16,6 +16,9 @@ var WorkspaceId = makeEntityId("WorkspaceId");
 var GraphId = makeEntityId("GraphId");
 var TaskId = makeEntityId("TaskId");
 var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
 var EngineRuntimeId = makeEntityId("EngineRuntimeId");
 var ConversationId = makeEntityId("ConversationId");
 var ActionId = makeEntityId("ActionId");

package/dist/src/tool-materializer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool-materializer capability seam.
+ *
+ * Defines the TOOL_MATERIALIZER service port that @rig/isolation-plugin
+ * consumes to build the runtime tool binaries (tool gateway, file tools,
+ * claude router, browser tools) without importing @rig/provider-plugin impl
+ * files directly. @rig/provider-plugin provides the capability; isolation-plugin
+ * resolves it via requireInstalledCapability — the SEAM-ONLY replacement for
+ * the four cross-plugin impl imports (§6.4).
+ *
+ * Pure: types + one branded id, no behaviour.
+ */
+import type { CapabilityId } from "./capability-id";
+/**
+ * The tool-materializer service: builds provider-plugin-owned runtime tool
+ * binaries into the given bin directory.
+ */
+export interface ToolMaterializerService {
+    /** Materialize the runtime tool gateway binary. Returns the path. */
+    materializeRuntimeToolGateway(binDir: string): Promise<string>;
+    /** Materialize the runtime file-tools binary. Returns the path. */
+    materializeRuntimeFileTools(targetDir: string): Promise<string>;
+    /** Materialize the Claude tool-router binary. Returns the path. */
+    materializeClaudeToolRouterBinary(projectRoot: string, targetDir: string): Promise<string>;
+    /** Materialize the runtime browser-tools binary. Returns the path. */
+    materializeRuntimeBrowserTools(targetDir: string): Promise<string>;
+    /** Synchronously resolve the runtime browser-tool binary name. */
+    runtimeBrowserToolBinaryName(): string;
+}
+/** Stable id string for the tool-materializer service capability. */
+export declare const TOOL_MATERIALIZER_CAPABILITY_ID = "provider.tool-materializer";
+/**
+ * The branded tool-materializer capability id. `defineCapability(TOOL_MATERIALIZER)`
+ * (provider and consumers independently) resolves to a `ToolMaterializerService`.
+ */
+export declare const TOOL_MATERIALIZER: CapabilityId<ToolMaterializerService>;

package/dist/src/tool-materializer.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/tool-materializer.ts
+var TOOL_MATERIALIZER_CAPABILITY_ID = "provider.tool-materializer";
+var TOOL_MATERIALIZER = makeCapabilityId(TOOL_MATERIALIZER_CAPABILITY_ID);
+export {
+  TOOL_MATERIALIZER_CAPABILITY_ID,
+  TOOL_MATERIALIZER
+};

package/dist/src/tool-registry.d.ts

@@ -0,0 +1,3 @@
+export declare const RUNTIME_SHELL_TOOL_NAMES: readonly string[];
+export declare const RUNTIME_FILE_TOOL_NAMES: readonly string[];
+export declare const RUNTIME_BROWSER_TOOL_NAMES: readonly string[];