@h-rig/contracts 0.0.6-alpha.18 → 0.0.6-alpha.181

package/dist/src/keybindings.d.ts

@@ -0,0 +1,71 @@
+import { Schema } from "effect";
+export declare const MAX_KEYBINDING_VALUE_LENGTH = 64;
+export declare const MAX_WHEN_EXPRESSION_DEPTH = 64;
+export declare const MAX_SCRIPT_ID_LENGTH = 24;
+export declare const MAX_KEYBINDINGS_COUNT = 256;
+export declare const SCRIPT_RUN_COMMAND_PATTERN: Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>;
+export declare const KeybindingCommand: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+export type KeybindingCommand = typeof KeybindingCommand.Type;
+export declare const KeybindingRule: Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly when: Schema.optional<Schema.Trim>;
+}>;
+export type KeybindingRule = typeof KeybindingRule.Type;
+export declare const KeybindingsConfig: Schema.$Array<Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly when: Schema.optional<Schema.Trim>;
+}>>;
+export type KeybindingsConfig = typeof KeybindingsConfig.Type;
+export declare const KeybindingShortcut: Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly metaKey: Schema.Boolean;
+    readonly ctrlKey: Schema.Boolean;
+    readonly shiftKey: Schema.Boolean;
+    readonly altKey: Schema.Boolean;
+    readonly modKey: Schema.Boolean;
+}>;
+export type KeybindingShortcut = typeof KeybindingShortcut.Type;
+export declare const KeybindingWhenNode: Schema.Schema<KeybindingWhenNode>;
+export type KeybindingWhenNode = {
+    type: "identifier";
+    name: string;
+} | {
+    type: "not";
+    node: KeybindingWhenNode;
+} | {
+    type: "and";
+    left: KeybindingWhenNode;
+    right: KeybindingWhenNode;
+} | {
+    type: "or";
+    left: KeybindingWhenNode;
+    right: KeybindingWhenNode;
+};
+export declare const ResolvedKeybindingRule: Schema.Struct<{
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly shortcut: Schema.Struct<{
+        readonly key: Schema.Trim;
+        readonly metaKey: Schema.Boolean;
+        readonly ctrlKey: Schema.Boolean;
+        readonly shiftKey: Schema.Boolean;
+        readonly altKey: Schema.Boolean;
+        readonly modKey: Schema.Boolean;
+    }>;
+    readonly whenAst: Schema.optional<Schema.Schema<KeybindingWhenNode>>;
+}>;
+export type ResolvedKeybindingRule = typeof ResolvedKeybindingRule.Type;
+export declare const ResolvedKeybindingsConfig: Schema.$Array<Schema.Struct<{
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly shortcut: Schema.Struct<{
+        readonly key: Schema.Trim;
+        readonly metaKey: Schema.Boolean;
+        readonly ctrlKey: Schema.Boolean;
+        readonly shiftKey: Schema.Boolean;
+        readonly altKey: Schema.Boolean;
+        readonly modKey: Schema.Boolean;
+    }>;
+    readonly whenAst: Schema.optional<Schema.Schema<KeybindingWhenNode>>;
+}>>;
+export type ResolvedKeybindingsConfig = typeof ResolvedKeybindingsConfig.Type;

package/dist/src/keybindings.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/layout.d.ts

@@ -0,0 +1,44 @@
+/** Directory name for a project's checked-in rig definition (`<root>/rig`). */
+export declare const RIG_DEFINITION_DIRNAME = "rig";
+/** Directory name for rig's per-project state (`<root>/.rig`). */
+export declare const RIG_STATE_DIRNAME = ".rig";
+export type RigLayout = {
+    projectRoot: string;
+    monorepoRoot: string;
+    definitionRoot: string;
+    runtimeWorkspaceRoot: string;
+    stateRoot: string;
+    configPath: string;
+    policyDir: string;
+    policyFile: string;
+    pluginsDir: string;
+    hooksDir: string;
+    toolsDir: string;
+    templatesDir: string;
+    validationDir: string;
+    stateDir: string;
+    logsDir: string;
+    notificationsDir: string;
+    runtimeDir: string;
+    distDir: string;
+    binDir: string;
+    pluginBinDir: string;
+    keybindingsPath: string;
+    controlPlaneEventsFile: string;
+};
+export type RuntimeWorkspaceLayout = {
+    workspaceDir: string;
+    rigRoot: string;
+    stateDir: string;
+    logsDir: string;
+    runtimeDir: string;
+    homeDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    sessionDir: string;
+    binDir: string;
+    distDir: string;
+    pluginBinDir: string;
+    contextPath: string;
+    controlPlaneEventsFile: string;
+};

package/dist/src/layout.js

@@ -0,0 +1,8 @@
+// @bun
+// packages/contracts/src/layout.ts
+var RIG_DEFINITION_DIRNAME = "rig";
+var RIG_STATE_DIRNAME = ".rig";
+export {
+  RIG_STATE_DIRNAME,
+  RIG_DEFINITION_DIRNAME
+};

package/dist/src/lifecycle-capabilities.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Typed ports for the default-lifecycle bundle's verification services.
+ *
+ * The dumb runtime substrate (rig-agent, harness-cli) must NOT import the
+ * lifecycle bundle (substrate->plugin cycle). Instead the bundle plugin
+ * registers executable impls under these ids on its
+ * `contributes.capabilities[].run`, and the runtime resolves them by id from
+ * `pluginHost.listExecutableCapabilities()`. These pure types are the shared
+ * contract for that seam — they carry no behaviour and import nothing.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { JournalCapability } from "./kernel";
+import type { RigAutomationConfig, StrictPrGreptileApiOptions } from "./control-plane-types";
+import type { RunCloseoutPhase, RunCloseoutPhaseOutcome } from "./run-journal";
+import type { RunJournal, RunJournalSessionManager } from "./run-session-journal";
+import type { TaskSourceUpdateResult, TaskTerminalStateInput } from "./task-source";
+import type { TaskReopenSummary } from "./task-data";
+/** Capability id the bundle registers its `taskVerify` orchestration under. */
+export declare const TASK_VERIFY_CAPABILITY_ID = "default-lifecycle.task-verify";
+/** Capability id the bundle registers its task validation runner under. */
+export declare const TASK_VALIDATION_CAPABILITY_ID = "default-lifecycle.task-validation";
+/** Capability id the bundle registers the completion-verification gate under. */
+export declare const COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+/** Capability id the bundle registers its run-worker closeout driver under. */
+export declare const RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+/** Capability id @rig/run-worker registers for writable run-session journal binding. */
+export declare const RUN_SESSION_JOURNAL_WRITER_CAPABILITY_ID = "run-worker.run-session-journal-writer";
+/** Capability id the bundle registers its lifecycle-owned task-source reflection under. */
+export declare const TASK_SOURCE_REFLECTION_CAPABILITY_ID = "default-lifecycle.task-source-reflection";
+/** Capability id the bundle registers its lifecycle-owned task terminal-state policy under. */
+export declare const TASK_TERMINAL_STATE_CAPABILITY_ID = "default-lifecycle.task-terminal-state";
+/** Capability id the bundle registers its lifecycle-owned task reopen policy under. */
+export declare const TASK_REOPEN_CAPABILITY_ID = "default-lifecycle.task-reopen";
+/** Capability id the bundle registers its agent-facing git helper surface under. */
+export declare const LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
+export interface TaskVerifyCapabilityInput {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+}
+/** Resolves true when the task is approved, false when verification rejects. */
+export type TaskVerifyCapabilityRun = (input: TaskVerifyCapabilityInput) => Promise<boolean>;
+/**
+ * The typed capability id the bundle provides its task-verify run under, phantom-
+ * typed with {@link TaskVerifyCapabilityRun} so `defineCapability(TASK_VERIFY_CAPABILITY)`
+ * resolves to the run function with no cast leaking to callers. Its string value
+ * is {@link TASK_VERIFY_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const TASK_VERIFY_CAPABILITY: CapabilityId<TaskVerifyCapabilityRun>;
+export interface TaskValidationCapabilityInput {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+    readonly validatorRegistry?: unknown;
+}
+/** Resolves true when task validation passes or is skipped, false on validation failures. */
+export type TaskValidationCapabilityRun = (input: TaskValidationCapabilityInput) => Promise<boolean>;
+export declare const TASK_VALIDATION_CAPABILITY: CapabilityId<TaskValidationCapabilityRun>;
+export interface CompletionVerificationCapabilityInput {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+}
+export interface CompletionVerificationCapabilityResult {
+    /** True when every completion gate passed; false when the gate blocks. */
+    readonly ok: boolean;
+}
+export type CompletionVerificationCapabilityRun = (input: CompletionVerificationCapabilityInput) => Promise<CompletionVerificationCapabilityResult>;
+/**
+ * The typed capability id the bundle provides its completion-verification gate
+ * under, phantom-typed with {@link CompletionVerificationCapabilityRun}. Its
+ * string value is {@link COMPLETION_VERIFICATION_CAPABILITY_ID}, so it indexes
+ * the same host entry.
+ */
+export declare const COMPLETION_VERIFICATION_CAPABILITY: CapabilityId<CompletionVerificationCapabilityRun>;
+export type LifecycleGitCommitOptions = {
+    projectRoot: string;
+    taskId?: string;
+    target: "monorepo" | "project" | "both";
+    message?: string;
+    allowEmpty: boolean;
+    scoped?: boolean;
+};
+export type LifecycleGitOpenPrOptions = {
+    projectRoot: string;
+    taskId?: string;
+    target?: "monorepo" | "project";
+    reviewer?: string;
+    base?: string;
+    title?: string;
+    body?: string;
+    draft?: boolean;
+};
+export type LifecycleGitOpenPrResult = {
+    url: string;
+    reviewer?: string;
+    reviewerSource?: "flag" | "task-config" | "changed-files" | "env";
+    target: "monorepo" | "project";
+    repoLabel: string;
+    branch: string;
+    base: string;
+};
+export type LifecycleGitAgentService = {
+    shouldScopeGitCommit(args: string[], hasTaskContext: boolean): boolean;
+    gitStatus(projectRoot: string, taskId?: string): void;
+    gitChanged(projectRoot: string, taskId: string | undefined, scoped: boolean): string[];
+    gitPreflight(projectRoot: string, taskId: string | undefined, strict: boolean): boolean;
+    gitSyncBranch(projectRoot: string, taskId?: string, targetRepo?: "monorepo" | "project"): void;
+    gitCommit(options: LifecycleGitCommitOptions): void;
+    gitSnapshot(projectRoot: string, taskId?: string, outputPath?: string): string;
+    gitOpenPr(options: LifecycleGitOpenPrOptions): LifecycleGitOpenPrResult;
+};
+export declare const LIFECYCLE_GIT_AGENT: CapabilityId<LifecycleGitAgentService>;
+export type RunTaskSourceReflectStatus = "under_review" | "ci_fixing" | "merging" | "closed" | "needs_attention";
+export type RunTaskSourceLifecycleStatus = "running" | RunTaskSourceReflectStatus | "cancelled";
+export type RunTaskSourceLifecycleRun = {
+    runId?: string | null;
+    taskId?: string | null;
+    sourceTask?: unknown;
+    worktreePath?: string | null;
+    logRoot?: string | null;
+    sessionPath?: string | null;
+    errorText?: string | null;
+};
+export type RunTaskSourceLifecycleOptions = {
+    errorText?: string | null;
+};
+export type RunTaskSourceStoppedOptions = RunTaskSourceLifecycleOptions & {
+    reason?: string | null;
+};
+export type TaskSourceReflectionInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly sourceTask?: unknown;
+    readonly runId?: string | null;
+    /** Generic source status to write. Omit/null for comment-only reflection. */
+    readonly status?: string | null;
+    /** Status text rendered in the lifecycle comment; defaults to `status`. */
+    readonly commentStatus?: string | null;
+    readonly summary: string;
+    readonly runtimeWorkspace?: string | null;
+    readonly logsDir?: string | null;
+    readonly sessionDir?: string | null;
+    readonly errorText?: string | null;
+    readonly prUrl?: string | null;
+};
+export type TaskSourceMergedPrReflectionInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly prUrl: string;
+    readonly sourceTask?: unknown;
+};
+export type TaskSourceReflectionResult = TaskSourceUpdateResult & {
+    /** Lifecycle-owned status projected into the source update request. */
+    readonly projectedStatus?: RunTaskSourceLifecycleStatus | null;
+};
+export interface TaskSourceReflectionService {
+    reflectTaskSourceStatus(input: TaskSourceReflectionInput): Promise<TaskSourceReflectionResult | null>;
+    reflectRunStarted(projectRoot: string, run: RunTaskSourceLifecycleRun, options?: RunTaskSourceLifecycleOptions): Promise<TaskSourceReflectionResult | null>;
+    reflectRunStopped(projectRoot: string, run: RunTaskSourceLifecycleRun, options?: RunTaskSourceStoppedOptions): Promise<TaskSourceReflectionResult | null>;
+    updateRunTaskSourceLifecycle(projectRoot: string, run: RunTaskSourceLifecycleRun, status: RunTaskSourceLifecycleStatus, summary: string, options?: RunTaskSourceLifecycleOptions): Promise<TaskSourceReflectionResult | null>;
+    closeMergedPr(input: TaskSourceMergedPrReflectionInput): Promise<TaskSourceReflectionResult | null>;
+}
+export declare const TASK_SOURCE_REFLECTION: CapabilityId<TaskSourceReflectionService>;
+export interface TaskTerminalStateService {
+    isTaskTerminal(input: TaskTerminalStateInput): Promise<boolean>;
+}
+export declare const TASK_TERMINAL_STATE: CapabilityId<TaskTerminalStateService>;
+export type TaskReopenInput = {
+    readonly projectRoot: string;
+    readonly all: boolean;
+    readonly taskId?: string;
+    readonly dryRun?: boolean;
+};
+/** Lifecycle-owned reopen policy for legacy `task reopen`; source plugin only performs config IO. */
+export interface TaskReopenService {
+    reopenTasks(input: TaskReopenInput): TaskReopenSummary;
+}
+export declare const TASK_REOPEN: CapabilityId<TaskReopenService>;
+export interface RunSessionJournalWriterService {
+    createRunJournal(sessionManager: RunJournalSessionManager, runId: string): Promise<RunJournal | null>;
+}
+/**
+ * Writable run-session journal factory. Kept separate from RUN_SESSION_JOURNAL so
+ * the read-model plugin remains projection/read-only and append ownership lives
+ * with the run-worker lifecycle package.
+ */
+export declare const RUN_SESSION_JOURNAL_WRITER: CapabilityId<RunSessionJournalWriterService>;
+export type RunCloseoutResultStatus = "merged" | "opened" | "skipped" | "needs-attention";
+export type RunCloseoutResult = {
+    status: RunCloseoutResultStatus;
+    prUrl?: string;
+    iterations: number;
+    feedback: readonly string[];
+};
+export type RunCloseoutValidationInput = {
+    projectRoot: string;
+    taskId: string;
+};
+export type RunCloseoutValidationRunner = (input: RunCloseoutValidationInput) => Promise<boolean> | boolean;
+export type RunCloseoutInput = {
+    projectRoot: string;
+    runId: string;
+    taskId: string;
+    branch: string;
+    workspace: string;
+    artifactRoot?: string | null;
+    config?: RigAutomationConfig | null;
+    sourceTask?: Record<string, unknown> | null;
+    steerPi: (message: string) => Promise<void>;
+    greptileApi?: StrictPrGreptileApiOptions;
+    runValidation?: RunCloseoutValidationRunner;
+    onValidationStart?: () => Promise<void> | void;
+    kernelJournal?: JournalCapability | null;
+    journalPhase: (phase: RunCloseoutPhase, outcome: RunCloseoutPhaseOutcome, detail?: string | null) => Promise<void> | void;
+    reflect: (status: RunTaskSourceReflectStatus, summary: string, options?: {
+        errorText?: string | null;
+    }) => Promise<void> | void;
+};
+export type RunCloseoutCapabilityRun = (input: RunCloseoutInput) => Promise<RunCloseoutResult>;
+/**
+ * The typed capability id the bundle provides its run-worker closeout driver
+ * under, so @rig/run-worker can close out by resolving the lifecycle capability
+ * instead of importing the lifecycle plugin implementation.
+ */
+export declare const RUN_CLOSEOUT_CAPABILITY: CapabilityId<RunCloseoutCapabilityRun>;

package/dist/src/lifecycle-capabilities.js

@@ -0,0 +1,45 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/lifecycle-capabilities.ts
+var TASK_VERIFY_CAPABILITY_ID = "default-lifecycle.task-verify";
+var TASK_VALIDATION_CAPABILITY_ID = "default-lifecycle.task-validation";
+var COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+var RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+var RUN_SESSION_JOURNAL_WRITER_CAPABILITY_ID = "run-worker.run-session-journal-writer";
+var TASK_SOURCE_REFLECTION_CAPABILITY_ID = "default-lifecycle.task-source-reflection";
+var TASK_TERMINAL_STATE_CAPABILITY_ID = "default-lifecycle.task-terminal-state";
+var TASK_REOPEN_CAPABILITY_ID = "default-lifecycle.task-reopen";
+var LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
+var TASK_VERIFY_CAPABILITY = makeCapabilityId(TASK_VERIFY_CAPABILITY_ID);
+var TASK_VALIDATION_CAPABILITY = makeCapabilityId(TASK_VALIDATION_CAPABILITY_ID);
+var COMPLETION_VERIFICATION_CAPABILITY = makeCapabilityId(COMPLETION_VERIFICATION_CAPABILITY_ID);
+var LIFECYCLE_GIT_AGENT = makeCapabilityId(LIFECYCLE_GIT_AGENT_CAPABILITY_ID);
+var TASK_SOURCE_REFLECTION = makeCapabilityId(TASK_SOURCE_REFLECTION_CAPABILITY_ID);
+var TASK_TERMINAL_STATE = makeCapabilityId(TASK_TERMINAL_STATE_CAPABILITY_ID);
+var TASK_REOPEN = makeCapabilityId(TASK_REOPEN_CAPABILITY_ID);
+var RUN_SESSION_JOURNAL_WRITER = makeCapabilityId(RUN_SESSION_JOURNAL_WRITER_CAPABILITY_ID);
+var RUN_CLOSEOUT_CAPABILITY = makeCapabilityId(RUN_CLOSEOUT_CAPABILITY_ID);
+export {
+  TASK_VERIFY_CAPABILITY_ID,
+  TASK_VERIFY_CAPABILITY,
+  TASK_VALIDATION_CAPABILITY_ID,
+  TASK_VALIDATION_CAPABILITY,
+  TASK_TERMINAL_STATE_CAPABILITY_ID,
+  TASK_TERMINAL_STATE,
+  TASK_SOURCE_REFLECTION_CAPABILITY_ID,
+  TASK_SOURCE_REFLECTION,
+  TASK_REOPEN_CAPABILITY_ID,
+  TASK_REOPEN,
+  RUN_SESSION_JOURNAL_WRITER_CAPABILITY_ID,
+  RUN_SESSION_JOURNAL_WRITER,
+  RUN_CLOSEOUT_CAPABILITY_ID,
+  RUN_CLOSEOUT_CAPABILITY,
+  LIFECYCLE_GIT_AGENT_CAPABILITY_ID,
+  LIFECYCLE_GIT_AGENT,
+  COMPLETION_VERIFICATION_CAPABILITY_ID,
+  COMPLETION_VERIFICATION_CAPABILITY
+};