@h-rig/contracts 0.0.0-e2e-live.20260630085347

package/dist/src/runtime-task-context.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure runtime-task-context data shapes.
+ *
+ * These are behaviour-free data types describing the per-task runtime context
+ * the substrate materializes and threads to agents and capabilities. They carry
+ * no logic and import nothing but the sibling `RuntimeBrowserContext` contract,
+ * so they belong in the neutral contracts layer (exactly like `memory.ts` /
+ * `lifecycle-capabilities.ts`).
+ *
+ * The fs-backed loaders/serializers that PRODUCE and VALIDATE these shapes stay
+ * in `@rig/runtime/control-plane/runtime/context.ts`, which re-exports these
+ * types for back-compat so existing `import … from ".../runtime/context"` sites
+ * are unaffected.
+ */
+import type { RuntimeBrowserContext } from "./browser";
+/** Retrieval weighting for shared-memory recall; pure config data. */
+export type RuntimeMemoryRetrievalConfig = {
+    topK: number;
+    lexicalWeight: number;
+    vectorWeight: number;
+    recencyWeight: number;
+    confidenceWeight: number;
+};
+/** The materialized shared-memory context handed to a runtime task. */
+export type RuntimeMemoryContext = {
+    canonicalPath: string;
+    canonicalRef: string;
+    canonicalBaseOid?: string;
+    hydratedPath: string;
+    createdFresh: boolean;
+    retrieval: RuntimeMemoryRetrievalConfig;
+};
+/** The source-task contract fields a runtime task carries through. */
+export type RuntimeSourceTaskContract = {
+    id: string;
+    title?: string;
+    description?: string;
+    body?: string;
+    acceptanceCriteria?: string;
+    acceptance_criteria?: string;
+    sourceIssueId?: string;
+    status?: string;
+    issueType?: string;
+    role?: string;
+    externalRef?: string;
+    scope?: string[];
+    validation?: string[];
+    validators?: string[];
+    labels?: string[];
+};
+/** The fully-resolved per-task runtime context. */
+export type RuntimeTaskContext = {
+    runtimeId: string;
+    taskId: string;
+    role: string;
+    scopes: string[];
+    validation: string[];
+    sourceTask?: RuntimeSourceTaskContract;
+    browser?: RuntimeBrowserContext;
+    workspaceDir: string;
+    artifactRoot?: string;
+    hostProjectRoot?: string;
+    monorepoMainRoot?: string;
+    monorepoBaseRef?: string;
+    monorepoBaseCommit?: string;
+    initialHeadCommits?: {
+        project?: string;
+        monorepo?: string;
+    };
+    initialDirtyFiles?: {
+        project?: string[];
+        monorepo?: string[];
+    };
+    stateDir: string;
+    logsDir: string;
+    sessionDir: string;
+    sessionFile: string;
+    policyFile: string;
+    binDir: string;
+    createdAt: string;
+    memory?: RuntimeMemoryContext;
+};

package/dist/src/runtime-task-context.js

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

package/dist/src/runtime.d.ts

@@ -0,0 +1,103 @@
+import { Schema } from "effect";
+export declare const RunKind: Schema.Literals<readonly ["adhoc", "task", "batch", "validation", "review"]>;
+export type RunKind = typeof RunKind.Type;
+export declare const RunMode: Schema.Literals<readonly ["interactive", "autonomous", "supervised"]>;
+export type RunMode = typeof RunMode.Type;
+export declare const RunStatus: Schema.Literals<readonly ["created", "queued", "preparing", "running", "waiting-approval", "waiting-user-input", "paused", "validating", "reviewing", "closing-out", "needs-attention", "completed", "failed", "stopped"]>;
+export type RunStatus = typeof RunStatus.Type;
+export declare const EngineSandboxMode: Schema.Literals<readonly ["read-only", "workspace-write", "danger-full-access"]>;
+export type EngineSandboxMode = typeof EngineSandboxMode.Type;
+export declare const IsolationMode: Schema.Literals<readonly ["none", "env", "worktree"]>;
+export type IsolationMode = typeof IsolationMode.Type;
+export declare const RuntimeStatus: Schema.Literals<readonly ["prepared", "starting", "running", "interrupted", "exited", "failed", "destroyed"]>;
+export type RuntimeStatus = typeof RuntimeStatus.Type;
+export declare const RunExecutionTarget: Schema.Literals<readonly ["local", "remote"]>;
+export type RunExecutionTarget = typeof RunExecutionTarget.Type;
+export declare const RunSummary: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "RunId">;
+    readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+    readonly taskId: Schema.NullOr<Schema.brand<Schema.Trim, "TaskId">>;
+    readonly title: Schema.Trim;
+    readonly runKind: Schema.Literals<readonly ["adhoc", "task", "batch", "validation", "review"]>;
+    readonly mode: Schema.Literals<readonly ["interactive", "autonomous", "supervised"]>;
+    readonly runtimeMode: Schema.Literals<readonly ["approval-required", "full-access"]>;
+    readonly interactionMode: Schema.Literals<readonly ["default", "plan"]>;
+    readonly status: Schema.Literals<readonly ["created", "queued", "preparing", "running", "waiting-approval", "waiting-user-input", "paused", "validating", "reviewing", "closing-out", "needs-attention", "completed", "failed", "stopped"]>;
+    readonly runtimeAdapter: Schema.Literal<"pi">;
+    readonly model: Schema.NullOr<Schema.Trim>;
+    readonly initialPrompt: Schema.NullOr<Schema.String>;
+    readonly executionTarget: Schema.optional<Schema.Literals<readonly ["local", "remote"]>>;
+    readonly remoteHostId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly remoteLeaseId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly remoteLeaseClaimedAt: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly activeRuntimeId: Schema.NullOr<Schema.brand<Schema.Trim, "EngineRuntimeId">>;
+    readonly latestMessageId: Schema.NullOr<Schema.Trim>;
+    readonly pendingApprovalCount: Schema.Int;
+    readonly pendingUserInputCount: Schema.Int;
+    readonly branch: Schema.NullOr<Schema.Trim>;
+    readonly worktreePath: Schema.NullOr<Schema.Trim>;
+    readonly errorText: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+    readonly startedAt: Schema.NullOr<Schema.String>;
+    readonly completedAt: Schema.NullOr<Schema.String>;
+}>;
+export type RunSummary = typeof RunSummary.Type;
+export declare const RuntimeSummary: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "EngineRuntimeId">;
+    readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly adapterKind: Schema.Literal<"pi">;
+    readonly executionTarget: Schema.optional<Schema.Literals<readonly ["local", "remote"]>>;
+    readonly remoteHostId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly status: Schema.Literals<readonly ["prepared", "starting", "running", "interrupted", "exited", "failed", "destroyed"]>;
+    readonly sandboxMode: Schema.Literals<readonly ["read-only", "workspace-write", "danger-full-access"]>;
+    readonly isolationMode: Schema.Literals<readonly ["none", "env", "worktree"]>;
+    readonly workspaceDir: Schema.NullOr<Schema.Trim>;
+    readonly homeDir: Schema.NullOr<Schema.Trim>;
+    readonly tmpDir: Schema.NullOr<Schema.Trim>;
+    readonly cacheDir: Schema.NullOr<Schema.Trim>;
+    readonly logsDir: Schema.NullOr<Schema.Trim>;
+    readonly stateDir: Schema.NullOr<Schema.Trim>;
+    readonly sessionDir: Schema.NullOr<Schema.Trim>;
+    readonly sessionLogPath: Schema.NullOr<Schema.Trim>;
+    readonly pid: Schema.NullOr<Schema.Int>;
+    readonly startedAt: Schema.NullOr<Schema.String>;
+    readonly updatedAt: Schema.String;
+    readonly exitedAt: Schema.NullOr<Schema.String>;
+}>;
+export type RuntimeSummary = typeof RuntimeSummary.Type;
+export declare const ApprovalStatus: Schema.Literals<readonly ["pending", "resolved"]>;
+export type ApprovalStatus = typeof ApprovalStatus.Type;
+export declare const ApprovalSummary: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly actionId: Schema.NullOr<Schema.Trim>;
+    readonly requestKind: Schema.Trim;
+    readonly status: Schema.Literals<readonly ["pending", "resolved"]>;
+    readonly payload: Schema.Unknown;
+    readonly createdAt: Schema.String;
+    readonly resolvedAt: Schema.NullOr<Schema.String>;
+}>;
+export type ApprovalSummary = typeof ApprovalSummary.Type;
+export declare const UserInputRequestSummary: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly status: Schema.Literals<readonly ["pending", "resolved"]>;
+    readonly payload: Schema.Unknown;
+    readonly createdAt: Schema.String;
+    readonly resolvedAt: Schema.NullOr<Schema.String>;
+}>;
+export type UserInputRequestSummary = typeof UserInputRequestSummary.Type;
+export declare const WorktreeSummary: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "WorktreeId">;
+    readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly taskId: Schema.NullOr<Schema.brand<Schema.Trim, "TaskId">>;
+    readonly branchName: Schema.Trim;
+    readonly path: Schema.Trim;
+    readonly status: Schema.Trim;
+    readonly createdAt: Schema.String;
+    readonly cleanedAt: Schema.NullOr<Schema.String>;
+}>;
+export type WorktreeSummary = typeof WorktreeSummary.Type;

package/dist/src/runtime.js

@@ -0,0 +1,210 @@
+// @bun
+// packages/contracts/src/runtime.ts
+import { Schema as Schema3 } from "effect";
+
+// packages/contracts/src/baseSchemas.ts
+import { Schema } from "effect";
+var TrimmedString = Schema.Trim;
+var TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
+var NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+var PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+var IsoDateTime = Schema.String;
+var makeEntityId = (brand) => TrimmedNonEmptyString.pipe(Schema.brand(brand));
+var ThreadId = makeEntityId("ThreadId");
+var ProjectId = makeEntityId("ProjectId");
+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");
+var ArtifactId = makeEntityId("ArtifactId");
+var WorktreeId = makeEntityId("WorktreeId");
+var ValidationResultId = makeEntityId("ValidationResultId");
+var ReviewResultId = makeEntityId("ReviewResultId");
+var CommandId = makeEntityId("CommandId");
+var EventId = makeEntityId("EventId");
+var MessageId = makeEntityId("MessageId");
+var TurnId = makeEntityId("TurnId");
+var ProviderItemId = makeEntityId("ProviderItemId");
+var RuntimeSessionId = makeEntityId("RuntimeSessionId");
+var RuntimeItemId = makeEntityId("RuntimeItemId");
+var RuntimeRequestId = makeEntityId("RuntimeRequestId");
+var RuntimeTaskId = makeEntityId("RuntimeTaskId");
+var ApprovalRequestId = makeEntityId("ApprovalRequestId");
+var CheckpointRef = makeEntityId("CheckpointRef");
+var RemoteEndpointId = makeEntityId("RemoteEndpointId");
+
+// packages/contracts/src/orchestration.ts
+import { Schema as Schema2 } from "effect";
+var ProviderKind = Schema2.Literals(["codex", "claude"]);
+var ProviderApprovalPolicy = Schema2.Literals([
+  "untrusted",
+  "on-failure",
+  "on-request",
+  "never"
+]);
+var ProviderSandboxMode = Schema2.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access"
+]);
+var ProviderServiceTier = Schema2.Literals(["fast", "flex"]);
+var RuntimeMode = Schema2.Literals(["approval-required", "full-access"]);
+var ProviderInteractionMode = Schema2.Literals(["default", "plan"]);
+var ProviderRequestKind = Schema2.Literals(["command", "file-read", "file-change"]);
+var ProviderApprovalDecision = Schema2.Literals([
+  "accept",
+  "acceptForSession",
+  "decline",
+  "cancel"
+]);
+var ProviderUserInputAnswers = Schema2.Record(Schema2.String, Schema2.Unknown);
+var PROVIDER_SEND_TURN_MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+var CHAT_ATTACHMENT_ID_MAX_CHARS = 128;
+var ChatAttachmentId = TrimmedNonEmptyString.check(Schema2.isMaxLength(CHAT_ATTACHMENT_ID_MAX_CHARS), Schema2.isPattern(/^[a-z0-9_-]+$/i));
+var ChatImageAttachment = Schema2.Struct({
+  type: Schema2.Literal("image"),
+  id: ChatAttachmentId,
+  name: TrimmedNonEmptyString.check(Schema2.isMaxLength(255)),
+  mimeType: TrimmedNonEmptyString.check(Schema2.isMaxLength(100), Schema2.isPattern(/^image\//i)),
+  sizeBytes: NonNegativeInt.check(Schema2.isLessThanOrEqualTo(PROVIDER_SEND_TURN_MAX_IMAGE_BYTES))
+});
+var ChatAttachment = Schema2.Union([ChatImageAttachment]);
+
+// packages/contracts/src/runtime.ts
+var RunKind = Schema3.Literals(["adhoc", "task", "batch", "validation", "review"]);
+var RunMode = Schema3.Literals(["interactive", "autonomous", "supervised"]);
+var RunStatus = Schema3.Literals([
+  "created",
+  "queued",
+  "preparing",
+  "running",
+  "waiting-approval",
+  "waiting-user-input",
+  "paused",
+  "validating",
+  "reviewing",
+  "closing-out",
+  "needs-attention",
+  "completed",
+  "failed",
+  "stopped"
+]);
+var EngineSandboxMode = Schema3.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access"
+]);
+var IsolationMode = Schema3.Literals(["none", "env", "worktree"]);
+var RuntimeStatus = Schema3.Literals([
+  "prepared",
+  "starting",
+  "running",
+  "interrupted",
+  "exited",
+  "failed",
+  "destroyed"
+]);
+var RunExecutionTarget = Schema3.Literals(["local", "remote"]);
+var RunSummary = Schema3.Struct({
+  id: RunId,
+  workspaceId: WorkspaceId,
+  taskId: Schema3.NullOr(TaskId),
+  title: TrimmedNonEmptyString,
+  runKind: RunKind,
+  mode: RunMode,
+  runtimeMode: RuntimeMode,
+  interactionMode: ProviderInteractionMode,
+  status: RunStatus,
+  runtimeAdapter: Schema3.Literal("pi"),
+  model: Schema3.NullOr(TrimmedNonEmptyString),
+  initialPrompt: Schema3.NullOr(Schema3.String),
+  executionTarget: Schema3.optional(RunExecutionTarget),
+  remoteHostId: Schema3.optional(Schema3.NullOr(TrimmedNonEmptyString)),
+  remoteLeaseId: Schema3.optional(Schema3.NullOr(TrimmedNonEmptyString)),
+  remoteLeaseClaimedAt: Schema3.optional(Schema3.NullOr(IsoDateTime)),
+  activeRuntimeId: Schema3.NullOr(EngineRuntimeId),
+  latestMessageId: Schema3.NullOr(TrimmedNonEmptyString),
+  pendingApprovalCount: NonNegativeInt,
+  pendingUserInputCount: NonNegativeInt,
+  branch: Schema3.NullOr(TrimmedNonEmptyString),
+  worktreePath: Schema3.NullOr(TrimmedNonEmptyString),
+  errorText: Schema3.NullOr(Schema3.String),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
+  startedAt: Schema3.NullOr(IsoDateTime),
+  completedAt: Schema3.NullOr(IsoDateTime)
+});
+var RuntimeSummary = Schema3.Struct({
+  id: EngineRuntimeId,
+  workspaceId: WorkspaceId,
+  runId: RunId,
+  adapterKind: Schema3.Literal("pi"),
+  executionTarget: Schema3.optional(RunExecutionTarget),
+  remoteHostId: Schema3.optional(Schema3.NullOr(TrimmedNonEmptyString)),
+  status: RuntimeStatus,
+  sandboxMode: EngineSandboxMode,
+  isolationMode: IsolationMode,
+  workspaceDir: Schema3.NullOr(TrimmedNonEmptyString),
+  homeDir: Schema3.NullOr(TrimmedNonEmptyString),
+  tmpDir: Schema3.NullOr(TrimmedNonEmptyString),
+  cacheDir: Schema3.NullOr(TrimmedNonEmptyString),
+  logsDir: Schema3.NullOr(TrimmedNonEmptyString),
+  stateDir: Schema3.NullOr(TrimmedNonEmptyString),
+  sessionDir: Schema3.NullOr(TrimmedNonEmptyString),
+  sessionLogPath: Schema3.NullOr(TrimmedNonEmptyString),
+  pid: Schema3.NullOr(NonNegativeInt),
+  startedAt: Schema3.NullOr(IsoDateTime),
+  updatedAt: IsoDateTime,
+  exitedAt: Schema3.NullOr(IsoDateTime)
+});
+var ApprovalStatus = Schema3.Literals(["pending", "resolved"]);
+var ApprovalSummary = Schema3.Struct({
+  id: TrimmedNonEmptyString,
+  runId: RunId,
+  actionId: Schema3.NullOr(TrimmedNonEmptyString),
+  requestKind: TrimmedNonEmptyString,
+  status: ApprovalStatus,
+  payload: Schema3.Unknown,
+  createdAt: IsoDateTime,
+  resolvedAt: Schema3.NullOr(IsoDateTime)
+});
+var UserInputRequestSummary = Schema3.Struct({
+  id: TrimmedNonEmptyString,
+  runId: RunId,
+  status: ApprovalStatus,
+  payload: Schema3.Unknown,
+  createdAt: IsoDateTime,
+  resolvedAt: Schema3.NullOr(IsoDateTime)
+});
+var WorktreeSummary = Schema3.Struct({
+  id: WorktreeId,
+  workspaceId: WorkspaceId,
+  runId: RunId,
+  taskId: Schema3.NullOr(TaskId),
+  branchName: TrimmedNonEmptyString,
+  path: TrimmedNonEmptyString,
+  status: TrimmedNonEmptyString,
+  createdAt: IsoDateTime,
+  cleanedAt: Schema3.NullOr(IsoDateTime)
+});
+export {
+  WorktreeSummary,
+  UserInputRequestSummary,
+  RuntimeSummary,
+  RuntimeStatus,
+  RunSummary,
+  RunStatus,
+  RunMode,
+  RunKind,
+  RunExecutionTarget,
+  IsolationMode,
+  EngineSandboxMode,
+  ApprovalSummary,
+  ApprovalStatus
+};

package/dist/src/session-asset-materializer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure session-asset-materializer contract.
+ *
+ * Neutral home for the "materialize plugin-contributed session assets into the
+ * workspace" seam so the plugin-host assembler (@rig/core/plugin-host-context)
+ * can trigger Pi skill + package materialization without importing
+ * @rig/provider-plugin (a floor->plugin cycle). The provider plugin owns the
+ * concrete impl (it knows the `.pi/skills` + `.pi/settings.json` layout) and
+ * registers it under {@link SESSION_ASSET_MATERIALIZER}; the assembler resolves
+ * it by id off the project plugin host and calls it. When no provider plugin is
+ * loaded the capability is simply absent and materialization is skipped — the
+ * same non-fatal default the inline implementation had.
+ *
+ * Carries no behaviour and imports only sibling contract types.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { RigConfig } from "./config";
+/** Capability id the provider plugin registers its session-asset materializer under. */
+export declare const SESSION_ASSET_MATERIALIZER_CAPABILITY_ID = "provider.session-asset-materializer";
+/**
+ * Materializes the plugin-contributed session assets (Pi skills declared via
+ * `contributes.skills`, and the config-declared Pi extension packages in
+ * `runtime.pi.packages`) into the project workspace. Idempotent and non-fatal:
+ * implementations log-and-continue on individual write failures so a
+ * materialization error can never deadlock harness boot.
+ */
+export interface SessionAssetMaterializerService {
+    materializeSessionAssets(projectRoot: string, config: RigConfig): Promise<void>;
+}
+/**
+ * Typed capability id the provider plugin provides and the plugin-host assembler
+ * requires. Phantom-typed with `SessionAssetMaterializerService` so `resolve(host)`
+ * returns the service with no cast leaking to callers.
+ */
+export declare const SESSION_ASSET_MATERIALIZER: CapabilityId<SessionAssetMaterializerService>;

package/dist/src/session-asset-materializer.js

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

package/dist/src/session-hook-materializer.d.ts

@@ -0,0 +1,41 @@
+import type { CapabilityId } from "./capability-id";
+import type { HookEvent, HookRegistration } from "./plugin";
+/** Stable id string for provider/runtime-owned session hook materialization. */
+export declare const SESSION_HOOK_MATERIALIZER_CAPABILITY_ID = "provider.session-hook-materializer";
+/**
+ * A plugin hook contribution prepared for the active session host.
+ *
+ * `typed` means the hook has a runtime implementation attached to the authored
+ * plugin object. Concrete materializers decide how their session host invokes
+ * that implementation; metadata-only hooks (no command and not typed) can be
+ * skipped by implementations.
+ */
+export interface PluginHookEntry {
+    readonly pluginName: string;
+    readonly hook: HookRegistration;
+    readonly typed?: boolean;
+}
+/** Alias naming the entries by the capability they are handed to. */
+export type SessionHookEntry = PluginHookEntry;
+/** Provider-owned materialization result; adapter ids are intentionally open. */
+export type SessionHookMaterializerResult = {
+    readonly adapterId: string;
+    readonly status: "materialized";
+    readonly path?: string;
+    readonly events?: readonly HookEvent[];
+} | {
+    readonly adapterId: string;
+    readonly status: "skipped";
+    readonly reason: string;
+};
+/**
+ * Materializes plugin-contributed hooks into whatever session host is active
+ * (Claude Code settings, Pi/OMP session integration, or another provider-owned
+ * substrate). The floor runtime resolves this capability and invokes it; it
+ * does not know adapter names, settings paths, or provider/session policy.
+ */
+export interface SessionHookMaterializerService {
+    materializeSessionHooks(projectRoot: string, entries: readonly PluginHookEntry[]): Promise<readonly SessionHookMaterializerResult[]> | readonly SessionHookMaterializerResult[];
+}
+/** Branded capability id for the session-hook materializer service. */
+export declare const SESSION_HOOK_MATERIALIZER: CapabilityId<SessionHookMaterializerService>;

package/dist/src/session-hook-materializer.js

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

package/dist/src/setup.d.ts

@@ -0,0 +1,154 @@
+/**
+ * cap:project-setup — cross-plugin seam.
+ *
+ * `@rig/cli-surface-plugin` (the `rig setup`/onboarding surface) runs project
+ * setup WITHOUT importing `@rig/init-plugin`: it requires this capability by id
+ * off the host. `@rig/init-plugin` OWNS the impl (`runSetup`) and registers it
+ * under this id. This file holds ONLY the pure seam vocabulary — no IO, no
+ * function-laden deps (those are the impl's concern, not the cross-plugin seam).
+ */
+import type { CapabilityId } from "./capability-id";
+import type { GitHubAuthStatus, GitHubProjectStatusField, GitHubProjectSummary } from "./github";
+/** Capability id the init/setup plugin registers its setup runner under. */
+export declare const PROJECT_SETUP_CAPABILITY_ID = "cap:project-setup";
+/**
+ * Where runs execute for this project. `kind` is the placement discriminator
+ * (e.g. "local" | "remote"); kept as a plain string so contracts stays free of
+ * the placement-domain enum.
+ */
+export type ProjectSetupPlacement = {
+    readonly alias: string;
+    readonly kind: "local" | "remote";
+    readonly host?: string;
+    readonly port?: number;
+    readonly token?: string | null;
+};
+/** Pure input to a project-setup pass. */
+export type ProjectSetupInput = {
+    readonly projectRoot: string;
+    readonly slug: string;
+    readonly placement: ProjectSetupPlacement;
+    readonly rewriteConfig?: boolean;
+    readonly ensurePi?: boolean;
+    readonly ensureLabels?: boolean;
+    readonly githubToken?: string | null;
+    readonly importGhToken?: boolean;
+};
+export type ProjectInitAuthMethod = "gh" | "token" | "device" | "skip";
+export type ProjectInitTaskSource = {
+    readonly kind: "github-issues";
+    readonly owner: string;
+    readonly repo: string;
+    readonly assignee?: string | undefined;
+} | {
+    readonly kind: "files";
+    readonly path: string;
+};
+export type ProjectInitInput = {
+    readonly projectRoot: string;
+    readonly demo?: boolean | undefined;
+    readonly repoSlug?: string | undefined;
+    readonly taskSource?: ProjectInitTaskSource | undefined;
+    readonly githubToken?: string | undefined;
+    readonly githubAuthMethod?: ProjectInitAuthMethod | undefined;
+    readonly githubProject?: "off" | string | undefined;
+    readonly githubProjectStatusField?: string | undefined;
+    readonly githubProjectStatuses?: Readonly<Record<string, string>> | undefined;
+    readonly yes?: boolean | undefined;
+    readonly repair?: boolean | undefined;
+    readonly privateStateOnly?: boolean | undefined;
+    readonly server?: "local" | "remote" | undefined;
+    readonly remoteAlias?: string | undefined;
+    readonly remoteHost?: string | undefined;
+    readonly remotePort?: number | undefined;
+    readonly remoteCheckout?: string | undefined;
+};
+export type ProjectInitResult = {
+    readonly mode: "control-plane" | "local-files" | "demo" | "task-source";
+    readonly projectRoot: string;
+    readonly messages: readonly string[];
+    readonly details: Record<string, unknown>;
+};
+export type ProjectInitGitHubProjectsInput = {
+    readonly projectRoot: string;
+    readonly owner: string;
+    readonly token?: string | null | undefined;
+};
+export type ProjectInitGitHubProjectsResult = {
+    readonly ok: true;
+    readonly projects: readonly GitHubProjectSummary[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly projects: readonly [];
+};
+export type ProjectInitProjectStatusFieldInput = {
+    readonly projectRoot: string;
+    readonly projectId: string;
+    readonly token?: string | null | undefined;
+};
+export type ProjectInitProjectStatusFieldResult = {
+    readonly ok: true;
+    readonly field: GitHubProjectStatusField;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type ProjectRepoSlug = {
+    readonly owner: string;
+    readonly repo: string;
+    readonly slug: string;
+};
+export type RigConfigStatus = {
+    readonly exists: boolean;
+    readonly valid: boolean;
+    readonly path: string;
+    readonly slug: string | null;
+    readonly reason?: string;
+};
+export type RigStateStatus = {
+    readonly valid: boolean;
+    readonly selected: string | null;
+    readonly project: string | null;
+    readonly reason?: string;
+};
+export type RigAuthValidation = {
+    readonly ok: boolean;
+    readonly source: "stored-token" | "gh" | "missing";
+    readonly login?: string | null;
+    readonly detail: string;
+    readonly status?: GitHubAuthStatus;
+};
+export type RigSetupStatus = {
+    readonly configured: boolean;
+    readonly projectRoot: string;
+    readonly slug: string | null;
+    readonly config: RigConfigStatus;
+    readonly state: RigStateStatus;
+    readonly auth: RigAuthValidation;
+    readonly reasons: readonly string[];
+};
+export type ProjectSetupResult = {
+    readonly repoSlug: string;
+    readonly placement: string;
+    readonly configWritten: boolean;
+    readonly labels: unknown;
+    readonly pi: unknown;
+    readonly status: RigSetupStatus;
+};
+/** The cohesive project-setup operation the CLI surface depends on. Async methods do IO. */
+export interface ProjectSetupService {
+    parseRepoSlug(value: string): ProjectRepoSlug;
+    detectOriginRepoSlug(input: {
+        readonly projectRoot: string;
+    }): string | null;
+    detectStartupStatus(input: {
+        readonly projectRoot: string;
+    }): Promise<RigSetupStatus>;
+    runSetup(input: ProjectSetupInput): Promise<ProjectSetupResult>;
+    listGitHubProjectsForInit(input: ProjectInitGitHubProjectsInput): Promise<ProjectInitGitHubProjectsResult>;
+    getGitHubProjectStatusFieldForInit(input: ProjectInitProjectStatusFieldInput): Promise<ProjectInitProjectStatusFieldResult>;
+    runInit(input: ProjectInitInput): Promise<ProjectInitResult>;
+}
+/** Typed capability id; string value is {@link PROJECT_SETUP_CAPABILITY_ID}. */
+export declare const PROJECT_SETUP: CapabilityId<ProjectSetupService>;

package/dist/src/setup.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/setup.ts
+var PROJECT_SETUP_CAPABILITY_ID = "cap:project-setup";
+var PROJECT_SETUP = makeCapabilityId(PROJECT_SETUP_CAPABILITY_ID);
+export {
+  PROJECT_SETUP_CAPABILITY_ID,
+  PROJECT_SETUP
+};