@h-rig/contracts 0.0.6-alpha.17 → 0.0.6-alpha.170

package/dist/src/memory.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Pure memory-service contract types.
+ *
+ * These types are the neutral home for the shared-memory data model so that the
+ * dumb runtime substrate (hooks, harness-cli, isolation, rig-agent) and the
+ * @rig/memory-plugin that owns the implementation can both reference them
+ * without a substrate->plugin import cycle. They carry no behaviour and import
+ * nothing — exactly like `lifecycle-capabilities.ts`.
+ *
+ * The plugin registers its executable `MemoryService` impl under the typed
+ * capability id {@link MEMORY} (whose string value is
+ * {@link MEMORY_SERVICE_CAPABILITY_ID}); the runtime resolves it by id from
+ * `pluginHost.listExecutableCapabilities()` via the `defineCapability` seam
+ * (`@rig/core/capability`), re-exported from the thin
+ * `@rig/runtime/control-plane/memory-service-port`.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { RuntimeMemoryRetrievalConfig, RuntimeTaskContext } from "./runtime-task-context";
+/** Capability id the memory plugin registers its `MemoryService` factory under. */
+export declare const MEMORY_SERVICE_CAPABILITY_ID = "memory.service";
+export declare const NO_MATCH_RETRIEVAL_CANONICAL_KEY = "__memory_recall__:none";
+export type MemoryDbStatement = {
+    sql: string;
+    args?: unknown[];
+};
+export type MemoryDbExecuteResult = {
+    rows: Array<Record<string, unknown>>;
+    rowsAffected?: number;
+};
+export type MemoryDbTransaction = {
+    execute(statement: MemoryDbStatement | string, args?: unknown[]): Promise<MemoryDbExecuteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    close(): void;
+};
+export type MemoryDbClient = {
+    execute(statement: MemoryDbStatement | string, args?: unknown[]): Promise<MemoryDbExecuteResult>;
+    transaction(mode: "write"): Promise<MemoryDbTransaction>;
+    close(): void;
+};
+export type MemoryEventType = "observed" | "promoted" | "corrected" | "superseded" | "retracted" | "reinforced" | "retrieved" | "feedback_recorded";
+export type MemoryStatus = "active" | "superseded" | "retracted";
+export type RetrievalFeedbackOutcome = "helpful" | "ignored" | "incorrect";
+type MemoryEventBase = {
+    eventId: string;
+    canonicalKey: string;
+    sourceRunId?: string | null;
+    sourceTaskId?: string | null;
+    branch?: string | null;
+    createdAt: string;
+};
+type MemoryProjectionSeed = {
+    summary: string;
+    kind: string;
+    category?: string | null;
+    confidence: number;
+    details?: Record<string, unknown> | null;
+};
+export type MemoryEventInput = (MemoryEventBase & MemoryProjectionSeed & {
+    eventType: "observed";
+}) | (MemoryEventBase & MemoryProjectionSeed & {
+    eventType: "promoted";
+    sourceCanonicalKey: string;
+}) | (MemoryEventBase & MemoryProjectionSeed & {
+    eventType: "corrected";
+    sourceCanonicalKey: string;
+}) | (MemoryEventBase & {
+    eventType: "superseded";
+    replacementCanonicalKey: string;
+}) | (MemoryEventBase & {
+    eventType: "retracted";
+}) | (MemoryEventBase & {
+    eventType: "reinforced";
+    confidence: number;
+}) | (MemoryEventBase & {
+    eventType: "retrieved";
+    retrievalQuery: string;
+    retrievalRank: number;
+}) | (MemoryEventBase & {
+    eventType: "feedback_recorded";
+    feedbackOutcome: RetrievalFeedbackOutcome;
+    retrievalRank: number;
+    retrievalQuery?: string | null;
+});
+export type MemoryEventMetadata = {
+    sourceCanonicalKey?: string | null;
+    replacementCanonicalKey?: string | null;
+    retrievalQuery?: string | null;
+    retrievalRank?: number | null;
+    feedbackOutcome?: RetrievalFeedbackOutcome | null;
+    summary?: string | null;
+    kind?: string | null;
+    category?: string | null;
+    confidence?: number | null;
+    details?: Record<string, unknown> | null;
+};
+export type MemoryEventRow = {
+    eventId: string;
+    eventType: MemoryEventType;
+    canonicalKey: string;
+    summary: string;
+    createdAt: string;
+};
+export type MemoryItemRow = {
+    canonicalKey: string;
+    summary: string;
+    kind: string | null;
+    category: string | null;
+    status: MemoryStatus;
+    confidence: number;
+    sourceRunId: string | null;
+    sourceTaskId: string | null;
+    branch: string | null;
+    details: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    lastEventId: string;
+    supersededBy: string | null;
+    embedding: number[] | null;
+};
+export type MemoryQueryOptions = {
+    canonicalKey?: string;
+    includeInactive?: boolean;
+};
+export type MemoryDb = {
+    path: string;
+    client: MemoryDbClient;
+    close(): Promise<void>;
+};
+/** A scored, ranked shared-memory item returned by the retrieval query. */
+export type MemoryQueryResult = {
+    canonicalKey: string;
+    summary: string;
+    kind: string | null;
+    category: string | null;
+    confidence: number;
+    updatedAt: string;
+    score: number;
+    lexicalScore: number;
+    vectorScore: number;
+    recencyScore: number;
+};
+/** Embeds text into vectors for memory retrieval; provider-agnostic. */
+export type MemoryEmbedder = {
+    embed(texts: string[]): Promise<number[][]>;
+};
+/** A materialized read-only snapshot of the canonical project-memory database. */
+export type CanonicalMemorySnapshot = {
+    repoPath: string;
+    baseOid: string;
+    dbPath: string;
+    createdFresh: boolean;
+    cleanup(): Promise<void>;
+};
+/**
+ * Minimal telemetry sink the memory command emits run events through. The
+ * substrate's concrete event bus (`@rig/runtime` `EventBusLike`) is a superset
+ * and is structurally assignable to this; the memory contract only depends on
+ * `emit`, so the pure contract stays free of any runtime/behaviour import.
+ */
+export interface MemoryCommandEventSink {
+    emit<TPayload extends Record<string, unknown>>(type: string, payload: TPayload): Promise<unknown>;
+}
+/** Options for the agent-facing `rig-agent memory <verb>` command dispatch. */
+export type ExecuteMemoryCommandOptions = {
+    projectRoot: string;
+    taskId: string;
+    runtimeContext: RuntimeTaskContext | null;
+    args: string[];
+    eventBus?: MemoryCommandEventSink;
+};
+/** The retrieval-query shape the substrate passes through to the impl. */
+export type MemoryQueryPortInput = {
+    query: string;
+    limit?: number;
+    retrieval?: RuntimeMemoryRetrievalConfig;
+};
+/**
+ * The cohesive set of shared-memory operations the runtime consumers depend on.
+ * This is pure capability VOCAB: the `@rig/memory-plugin` provides a concrete
+ * impl (statically checked against this interface via `MemoryCap.provide`), and
+ * the substrate only ever sees this contract — resolved by id off a plugin host
+ * with no `as unknown as` at any call site.
+ */
+export interface MemoryService {
+    executeMemoryCommand(options: ExecuteMemoryCommandOptions): Promise<string>;
+    readCanonicalMemoryDb(projectRoot: string): Promise<CanonicalMemorySnapshot>;
+    openMemoryDb(dbPath: string): Promise<MemoryDb>;
+    queryRelevantMemory(db: MemoryDb, input: MemoryQueryPortInput): Promise<MemoryQueryResult[]>;
+    formatMemoryQueryResults(results: MemoryQueryResult[]): string;
+}
+/**
+ * The typed capability id the memory plugin provides and consumers require.
+ * Phantom-typed with `MemoryService` so `MemoryCap.require(host)` returns a
+ * `MemoryService` with no cast leaking to callers. Its string value is
+ * {@link MEMORY_SERVICE_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const MEMORY: CapabilityId<MemoryService>;
+export {};

package/dist/src/memory.js

@@ -0,0 +1,15 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/memory.ts
+var MEMORY_SERVICE_CAPABILITY_ID = "memory.service";
+var NO_MATCH_RETRIEVAL_CANONICAL_KEY = "__memory_recall__:none";
+var MEMORY = makeCapabilityId(MEMORY_SERVICE_CAPABILITY_ID);
+export {
+  NO_MATCH_RETRIEVAL_CANONICAL_KEY,
+  MEMORY_SERVICE_CAPABILITY_ID,
+  MEMORY
+};

package/dist/src/model.d.ts

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+import { ProviderKind } from "./orchestration";
+export declare const CODEX_REASONING_EFFORT_OPTIONS: readonly ["xhigh", "high", "medium", "low"];
+export type CodexReasoningEffort = (typeof CODEX_REASONING_EFFORT_OPTIONS)[number];
+export declare const CodexModelOptions: Schema.Struct<{
+    readonly reasoningEffort: Schema.optional<Schema.Literals<readonly ["xhigh", "high", "medium", "low"]>>;
+    readonly fastMode: Schema.optional<Schema.Boolean>;
+}>;
+export type CodexModelOptions = typeof CodexModelOptions.Type;
+export declare const ClaudeModelOptions: Schema.Struct<{}>;
+export type ClaudeModelOptions = typeof ClaudeModelOptions.Type;
+export declare const ProviderModelOptions: Schema.Struct<{
+    readonly codex: Schema.optional<Schema.Struct<{
+        readonly reasoningEffort: Schema.optional<Schema.Literals<readonly ["xhigh", "high", "medium", "low"]>>;
+        readonly fastMode: Schema.optional<Schema.Boolean>;
+    }>>;
+    readonly claude: Schema.optional<Schema.Struct<{}>>;
+}>;
+export type ProviderModelOptions = typeof ProviderModelOptions.Type;
+export declare const MODEL_OPTIONS_BY_PROVIDER: {
+    readonly codex: readonly [{
+        readonly slug: "gpt-5.4";
+        readonly name: "GPT-5.4";
+    }, {
+        readonly slug: "gpt-5.3-codex";
+        readonly name: "GPT-5.3 Codex";
+    }, {
+        readonly slug: "gpt-5.3-codex-spark";
+        readonly name: "GPT-5.3 Codex Spark";
+    }, {
+        readonly slug: "gpt-5.2-codex";
+        readonly name: "GPT-5.2 Codex";
+    }, {
+        readonly slug: "gpt-5.2";
+        readonly name: "GPT-5.2";
+    }];
+    readonly claude: readonly [{
+        readonly slug: "claude-sonnet-4-6";
+        readonly name: "Claude Sonnet 4.6";
+    }, {
+        readonly slug: "claude-opus-4-1";
+        readonly name: "Claude Opus 4.1";
+    }, {
+        readonly slug: "claude-3-7-sonnet-latest";
+        readonly name: "Claude 3.7 Sonnet";
+    }];
+};
+export type ModelOptionsByProvider = typeof MODEL_OPTIONS_BY_PROVIDER;
+type BuiltInModelSlug = ModelOptionsByProvider[ProviderKind][number]["slug"];
+export type ModelSlug = BuiltInModelSlug | (string & {});
+export declare const DEFAULT_MODEL_BY_PROVIDER: {
+    readonly codex: "gpt-5.4";
+    readonly claude: "claude-sonnet-4-6";
+};
+export declare const MODEL_SLUG_ALIASES_BY_PROVIDER: {
+    readonly codex: {
+        readonly "5.4": "gpt-5.4";
+        readonly "5.3": "gpt-5.3-codex";
+        readonly "gpt-5.3": "gpt-5.3-codex";
+        readonly "5.3-spark": "gpt-5.3-codex-spark";
+        readonly "gpt-5.3-spark": "gpt-5.3-codex-spark";
+    };
+    readonly claude: {
+        readonly sonnet: "claude-sonnet-4-6";
+        readonly opus: "claude-opus-4-1";
+        readonly "3.7-sonnet": "claude-3-7-sonnet-latest";
+    };
+};
+export declare const REASONING_EFFORT_OPTIONS_BY_PROVIDER: {
+    readonly codex: readonly ["xhigh", "high", "medium", "low"];
+    readonly claude: readonly [];
+};
+export declare const DEFAULT_REASONING_EFFORT_BY_PROVIDER: {
+    readonly codex: "high";
+    readonly claude: null;
+};
+export {};

package/dist/src/native-toolchain.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Mechanical native-toolchain capability seams.
+ *
+ * These contracts describe binary build/materialization services only. Repo
+ * meaning, task scoping, repo-native git wrappers, and git workflow semantics
+ * belong to repo contracts; native-toolchain providers only locate, compile, or
+ * materialize binaries.
+ *
+ * Pure: types + branded ids, no behaviour.
+ */
+import type { CapabilityId } from "./capability-id";
+export type NativeToolchainBinaryKind = "executable" | "dynamic-library";
+export interface NativeToolchainTarget {
+    readonly platform: string;
+    readonly arch: string;
+    readonly triple?: string;
+    readonly abi?: string;
+}
+export interface NativeToolchainBinaryArtifact {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: NativeToolchainBinaryKind;
+    readonly target?: NativeToolchainTarget;
+}
+export interface NativeToolchainBinaryBuildInput {
+    readonly projectRoot: string;
+    readonly name: string;
+    readonly sourcePath: string;
+    readonly outputPath: string;
+    readonly kind: NativeToolchainBinaryKind;
+    readonly target?: NativeToolchainTarget;
+    readonly buildArgs?: readonly string[];
+    readonly defines?: Readonly<Record<string, string>>;
+}
+export interface NativeToolchainBinaryMaterializeInput {
+    readonly projectRoot: string;
+    readonly name: string;
+    readonly targetDir: string;
+    readonly target?: NativeToolchainTarget;
+}
+export interface NativeToolchainBinaryBuildService {
+    buildNativeBinary(input: NativeToolchainBinaryBuildInput): Promise<NativeToolchainBinaryArtifact>;
+    materializeNativeBinary(input: NativeToolchainBinaryMaterializeInput): Promise<NativeToolchainBinaryArtifact>;
+}
+export declare const NATIVE_TOOLCHAIN_BINARY_BUILD_CAPABILITY_ID = "native-toolchain.binary-build";
+export declare const NATIVE_TOOLCHAIN_BINARY_BUILD: CapabilityId<NativeToolchainBinaryBuildService>;

package/dist/src/native-toolchain.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/native-toolchain.ts
+var NATIVE_TOOLCHAIN_BINARY_BUILD_CAPABILITY_ID = "native-toolchain.binary-build";
+var NATIVE_TOOLCHAIN_BINARY_BUILD = makeCapabilityId(NATIVE_TOOLCHAIN_BINARY_BUILD_CAPABILITY_ID);
+export {
+  NATIVE_TOOLCHAIN_BINARY_BUILD_CAPABILITY_ID,
+  NATIVE_TOOLCHAIN_BINARY_BUILD
+};

package/dist/src/notify.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure NOTIFY capability vocab.
+ *
+ * The neutral home for the notification event/target data types and the typed
+ * capability seam so the floor (and any consumer) can resolve a notifier off a
+ * plugin host WITHOUT importing the provider package. Carries no behaviour —
+ * exactly like `browser.ts` / `memory.ts`.
+ *
+ * `@rig/notifications-plugin` provides the concrete `NotifyService` impl
+ * (config load + target selection = policy) under
+ * {@link NOTIFY_SERVICE_CAPABILITY} via the `defineCapability` seam.
+ */
+import type { CapabilityId } from "./capability-id";
+/** A Rig lifecycle event eligible for outbound notification. */
+export type RigEvent = {
+    id?: string;
+    runId?: string;
+    timestamp?: string;
+    type: string;
+    payload?: Record<string, unknown>;
+};
+/** A configured outbound notification channel. */
+export type NotificationTarget = {
+    id: string;
+    type: "slack-webhook" | "linear-webhook" | "notion-webhook" | "generic-webhook";
+    url: string;
+    enabled?: boolean;
+    events?: string[];
+    headers?: Record<string, string>;
+};
+/** The on-disk notification policy (`.rig/notifications.json`). */
+export type NotificationConfig = {
+    targets: NotificationTarget[];
+};
+/** Capability id the notifications plugin registers its `NotifyService` under. */
+export declare const NOTIFY_SERVICE_CAPABILITY_ID = "notify.dispatch";
+/**
+ * The cohesive notify operation consumers depend on. The impl owns the policy:
+ * which targets receive which events, loaded from the project's
+ * `.rig/notifications.json`. Returns the count of targets successfully notified.
+ */
+export interface NotifyService {
+    notify(event: RigEvent): Promise<number>;
+}
+/** Typed capability id the notifications plugin provides and consumers require. */
+export declare const NOTIFY_SERVICE_CAPABILITY: CapabilityId<NotifyService>;

package/dist/src/notify.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/notify.ts
+var NOTIFY_SERVICE_CAPABILITY_ID = "notify.dispatch";
+var NOTIFY_SERVICE_CAPABILITY = makeCapabilityId(NOTIFY_SERVICE_CAPABILITY_ID);
+export {
+  NOTIFY_SERVICE_CAPABILITY_ID,
+  NOTIFY_SERVICE_CAPABILITY
+};

package/dist/src/orchestration.d.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+export declare const ProviderKind: Schema.Literals<readonly ["codex", "claude"]>;
+export type ProviderKind = typeof ProviderKind.Type;
+export declare const ProviderApprovalPolicy: Schema.Literals<readonly ["untrusted", "on-failure", "on-request", "never"]>;
+export type ProviderApprovalPolicy = typeof ProviderApprovalPolicy.Type;
+export declare const ProviderSandboxMode: Schema.Literals<readonly ["read-only", "workspace-write", "danger-full-access"]>;
+export type ProviderSandboxMode = typeof ProviderSandboxMode.Type;
+export declare const ProviderServiceTier: Schema.Literals<readonly ["fast", "flex"]>;
+export type ProviderServiceTier = typeof ProviderServiceTier.Type;
+export declare const RuntimeMode: Schema.Literals<readonly ["approval-required", "full-access"]>;
+export type RuntimeMode = typeof RuntimeMode.Type;
+export declare const DEFAULT_RUNTIME_MODE: RuntimeMode;
+export declare const ProviderInteractionMode: Schema.Literals<readonly ["default", "plan"]>;
+export type ProviderInteractionMode = typeof ProviderInteractionMode.Type;
+export declare const DEFAULT_PROVIDER_INTERACTION_MODE: ProviderInteractionMode;
+export declare const ProviderRequestKind: Schema.Literals<readonly ["command", "file-read", "file-change"]>;
+export type ProviderRequestKind = typeof ProviderRequestKind.Type;
+export declare const ProviderApprovalDecision: Schema.Literals<readonly ["accept", "acceptForSession", "decline", "cancel"]>;
+export type ProviderApprovalDecision = typeof ProviderApprovalDecision.Type;
+export declare const ProviderUserInputAnswers: Schema.$Record<Schema.String, Schema.Unknown>;
+export type ProviderUserInputAnswers = typeof ProviderUserInputAnswers.Type;
+export declare const PROVIDER_SEND_TURN_MAX_INPUT_CHARS = 120000;
+export declare const PROVIDER_SEND_TURN_MAX_ATTACHMENTS = 8;
+export declare const PROVIDER_SEND_TURN_MAX_IMAGE_BYTES: number;
+declare const ChatAttachmentId: Schema.Trim;
+export type ChatAttachmentId = typeof ChatAttachmentId.Type;
+export declare const ChatImageAttachment: Schema.Struct<{
+    readonly type: Schema.Literal<"image">;
+    readonly id: Schema.Trim;
+    readonly name: Schema.Trim;
+    readonly mimeType: Schema.Trim;
+    readonly sizeBytes: Schema.Int;
+}>;
+export type ChatImageAttachment = typeof ChatImageAttachment.Type;
+export declare const ChatAttachment: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"image">;
+    readonly id: Schema.Trim;
+    readonly name: Schema.Trim;
+    readonly mimeType: Schema.Trim;
+    readonly sizeBytes: Schema.Int;
+}>]>;
+export type ChatAttachment = typeof ChatAttachment.Type;
+export {};