oh-my-super-agent 0.1.0

package/dist/src/events/bus.js

@@ -0,0 +1,115 @@
+import { join } from "node:path";
+import { assertOpaqueId } from "../domain/records.js";
+import { assertOutboxStore, } from "../outbox/store.js";
+import { assertSchema, loadJsonSchema } from "../runtime/schema.js";
+import { bindRuntimeComponent, createRuntimeComposition, } from "../runtime/composition.js";
+import { OMS_EVENT_KINDS } from "./kinds.js";
+const EVENT_BUS = Symbol("OMS runtime event bus");
+const EVENT_BUSES = new WeakSet();
+const TYPED_RUNTIME_EVENTS = new WeakSet();
+export function createRuntimeEventBus(options) {
+    const outbox = options.outbox;
+    const packageRoot = options.packageRoot;
+    const composition = options.composition ?? createRuntimeComposition();
+    assertOutboxStore(outbox);
+    const schemas = new Map(OMS_EVENT_KINDS.map((kind) => [
+        kind,
+        loadJsonSchema(join(packageRoot, "schemas", "events", `${kind}.schema.json`)),
+    ]));
+    function validate(event, expectedKind) {
+        if (event.event_kind !== expectedKind)
+            throw new Error(`runtime event is not ${expectedKind}`);
+        const schema = schemas.get(expectedKind);
+        if (!schema)
+            throw new Error(`runtime event schema is missing: ${expectedKind}`);
+        assertSchema(event.payload, schema, `${expectedKind} payload`);
+        const typed = deepFreeze(structuredClone(event));
+        TYPED_RUNTIME_EVENTS.add(typed);
+        return typed;
+    }
+    const bus = Object.freeze({
+        [EVENT_BUS]: true,
+        publish(kind, identity, payload) {
+            assertEventKind(kind);
+            const capturedIdentity = {
+                sourceId: identity.sourceId,
+                sourceVersion: identity.sourceVersion,
+                dedupeKey: identity.dedupeKey,
+                occurredAt: identity.occurredAt,
+            };
+            const detachedPayload = structuredClone(payload);
+            const schema = schemas.get(kind);
+            if (!schema)
+                throw new Error(`runtime event schema is missing: ${kind}`);
+            assertSchema(detachedPayload, schema, `${kind} payload before publish`);
+            const published = outbox.publish({
+                eventKind: kind,
+                sourceId: assertOpaqueId(capturedIdentity.sourceId, "event source id"),
+                sourceVersion: capturedIdentity.sourceVersion,
+                dedupeKey: assertOpaqueId(capturedIdentity.dedupeKey, "event dedupe key"),
+                occurredAt: capturedIdentity.occurredAt,
+                payload: detachedPayload,
+            });
+            return Object.freeze({ status: published.status, event: validate(published.event, kind) });
+        },
+        read(eventId, kind) {
+            assertEventKind(kind);
+            return validate(outbox.readEvent(assertOpaqueId(eventId, "runtime event id")), kind);
+        },
+        find(kind, identity) {
+            assertEventKind(kind);
+            const capturedIdentity = {
+                sourceId: assertOpaqueId(identity.sourceId, "event source id"),
+                sourceVersion: identity.sourceVersion,
+                dedupeKey: assertOpaqueId(identity.dedupeKey, "event dedupe key"),
+                occurredAt: identity.occurredAt,
+            };
+            const matches = outbox.listEvents().filter((event) => (event.event_kind === kind
+                && event.source_id === capturedIdentity.sourceId
+                && event.source_version === capturedIdentity.sourceVersion
+                && event.dedupe_key === capturedIdentity.dedupeKey
+                && event.occurred_at === capturedIdentity.occurredAt));
+            if (matches.length > 1)
+                throw new Error("runtime event identity is ambiguous");
+            return matches[0] ? validate(matches[0], kind) : undefined;
+        },
+        pending(consumerId, kind) {
+            assertEventKind(kind);
+            const pending = outbox.listPending(assertOpaqueId(consumerId, "runtime event consumer"))
+                .filter((event) => event.event_kind === kind)
+                .map((event) => validate(event, kind));
+            return Object.freeze(pending);
+        },
+    });
+    bindRuntimeComponent(bus, composition);
+    EVENT_BUSES.add(bus);
+    return bus;
+}
+export function assertRuntimeEventBus(value) {
+    if (typeof value !== "object" || value === null || !EVENT_BUSES.has(value)) {
+        throw new Error("event operation requires a real OMS runtime event bus");
+    }
+    if (!Object.isFrozen(value))
+        throw new Error("runtime event bus lost its authority boundary");
+}
+export function assertTypedRuntimeEvent(value, kind) {
+    if (typeof value !== "object" || value === null || !TYPED_RUNTIME_EVENTS.has(value)) {
+        throw new Error(`quota authority requires a real stored ${kind} event`);
+    }
+    if (!Object.isFrozen(value) || value.event_kind !== kind) {
+        throw new Error(`runtime event lost its ${kind} authority boundary`);
+    }
+}
+function assertEventKind(value) {
+    if (!OMS_EVENT_KINDS.includes(value))
+        throw new Error("unknown OMS runtime event kind");
+}
+function deepFreeze(value, seen = new Set()) {
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    return Object.freeze(value);
+}
+//# sourceMappingURL=bus.js.map

package/dist/src/events/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../../src/events/bus.ts"],"names":[],"mappings":"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"}

package/dist/src/events/kinds.d.ts

@@ -0,0 +1,126 @@
+import type { QuotaObservationReference } from "../runtime/quota.js";
+import type { ProviderObservation } from "../hooks/provider.js";
+export interface NativeHookTicketAuthority extends Record<string, unknown> {
+    ticket_id: string;
+    ticket_version: number;
+    ticket_attempt: number;
+    ticket_actor: string;
+    lease_token: string;
+}
+export declare const OMS_EVENT_KINDS: readonly ["native-hook-observed", "provider-observed", "github-observed", "structured-role-completed", "dispatch-delivery-requested", "ticket-resume-due", "run-heartbeat-due", "watchdog-lease-expired", "watchdog-session-stalled", "watchdog-outbox-stalled", "slack-notification-requested"];
+export type OmsEventKind = (typeof OMS_EVENT_KINDS)[number];
+export interface DispatchDeliveryRequestedPayload extends Record<string, unknown> {
+    dispatch_id: string;
+    dispatch_version: 1;
+    worker_record_id: string;
+    ticket_id: string;
+    attempt: number;
+    lease_token: string;
+    requested_at: string;
+}
+export interface NativeHookObservedPayload extends Record<string, unknown> {
+    delivery_id: string;
+    hook_kind: "session-started" | "session-heartbeat" | "session-stopped" | "quota-exhausted" | "quota-available";
+    session_id: string;
+    session_version: number;
+    role_id: string;
+    engine: "claude" | "codex";
+    mode: "pane" | "goal" | "exec";
+    run_id: string | null;
+    ticket_id: string | null;
+    native_session_ref: string;
+    tmux_pane_id: string | null;
+    observed_at: string;
+    heartbeat_deadline_at: string | null;
+    quota_valid_until: string | null;
+    quota_resume_at: string | null;
+    source_sha256: string;
+    ticket_authority: NativeHookTicketAuthority | null;
+}
+export interface GithubObservedPayload extends Record<string, unknown> {
+    observation_key: string;
+    observation_kind: "issue" | "comment" | "label" | "branch" | "pull_request" | "review" | "check";
+    repository: string;
+    source_id_sha256: string;
+    source_version_sha256: string;
+    change: "present" | "removed";
+    presence_generation: number;
+    observed_at: string;
+    payload_sha256: string;
+    snapshot_file: string;
+}
+export interface StructuredRoleCompletedPayload extends Record<string, unknown> {
+    schema_version: 1;
+    request_id: string;
+    role_id: "oms.grader.claude" | "oms.bounded-dreamer";
+    result_gate_id: string;
+    dispatch_id: string;
+    ticket_id: string;
+    claude_session_id: string;
+    submitted_at: string;
+    result_sha256: string;
+    terminal_authority: false;
+}
+export interface TicketResumeDuePayload extends Record<string, unknown> {
+    ticket_id: string;
+    ticket_version: number;
+    ticket_attempt: number;
+    ticket_actor: string;
+    ticket_lease_token: string | null;
+    role_id: string | null;
+    quota_observation: QuotaObservationReference | null;
+    session_version: number | null;
+    due_at: string;
+    emitted_at: string;
+    latency_ms: number;
+    policy_digest: string;
+}
+export interface RunHeartbeatDuePayload extends Record<string, unknown> {
+    run_id: string;
+    expected_head_sha256: string;
+    emitted_at: string;
+}
+export interface WatchdogLeaseExpiredPayload extends Record<string, unknown> {
+    ticket_id: string;
+    ticket_version: number;
+    ticket_attempt: number;
+    ticket_actor: string;
+    lease_token: string;
+    lease_expires_at: string;
+    observed_at: string;
+}
+export interface WatchdogSessionStalledPayload extends Record<string, unknown> {
+    session_id: string;
+    session_version: number;
+    heartbeat_deadline_at: string;
+    observed_at: string;
+}
+export interface WatchdogOutboxStalledPayload extends Record<string, unknown> {
+    event_id: string;
+    consumer_id: string;
+    occurred_at: string;
+    observed_at: string;
+    age_ms: number;
+}
+export interface SlackNotificationRequestedPayload extends Record<string, unknown> {
+    subject_kind: "run" | "ticket" | "session" | "report";
+    subject_id: string;
+    source_version: number;
+    template_id: string;
+    severity: "info" | "warning" | "error";
+    artifact_ref: string;
+    channel_ref: string;
+}
+export interface EventPayloadMap {
+    "native-hook-observed": NativeHookObservedPayload;
+    "provider-observed": ProviderObservation;
+    "github-observed": GithubObservedPayload;
+    "structured-role-completed": StructuredRoleCompletedPayload;
+    "dispatch-delivery-requested": DispatchDeliveryRequestedPayload;
+    "ticket-resume-due": TicketResumeDuePayload;
+    "run-heartbeat-due": RunHeartbeatDuePayload;
+    "watchdog-lease-expired": WatchdogLeaseExpiredPayload;
+    "watchdog-session-stalled": WatchdogSessionStalledPayload;
+    "watchdog-outbox-stalled": WatchdogOutboxStalledPayload;
+    "slack-notification-requested": SlackNotificationRequestedPayload;
+}

package/dist/src/events/kinds.js

@@ -0,0 +1,14 @@
+export const OMS_EVENT_KINDS = [
+    "native-hook-observed",
+    "provider-observed",
+    "github-observed",
+    "structured-role-completed",
+    "dispatch-delivery-requested",
+    "ticket-resume-due",
+    "run-heartbeat-due",
+    "watchdog-lease-expired",
+    "watchdog-session-stalled",
+    "watchdog-outbox-stalled",
+    "slack-notification-requested",
+];
+//# sourceMappingURL=kinds.js.map

package/dist/src/events/kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.js","sourceRoot":"","sources":["../../../src/events/kinds.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,sBAAsB;IACtB,mBAAmB;IACnB,iBAAiB;IACjB,2BAA2B;IAC3B,6BAA6B;IAC7B,mBAAmB;IACnB,mBAAmB;IACnB,wBAAwB;IACxB,0BAA0B;IAC1B,yBAAyB;IACzB,8BAA8B;CACtB,CAAC"}

package/dist/src/evidence/immutable-file.d.ts

@@ -0,0 +1,12 @@
+export declare class ImmutableFileConflictError extends Error {
+    constructor(path: string);
+}
+export interface StableDirectory {
+    readonly path: string;
+    assertUnchanged(): void;
+    close(): void;
+}
+export declare function openStableDirectory(path: string, label: string): StableDirectory;
+export declare function readImmutableFile(path: string, maxBytes?: number): Buffer;
+export declare function writeImmutableFile(path: string, bytes: Buffer): "created" | "replayed";
+export declare function assertFileInside(directory: StableDirectory, path: string): void;

package/dist/src/evidence/immutable-file.js

@@ -0,0 +1,141 @@
+import { chmodSync, closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { fsyncDirectory, validateExistingDirectory } from "../utils/fs.js";
+const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+export class ImmutableFileConflictError extends Error {
+    constructor(path) {
+        super(`immutable file already exists with different content: ${path}`);
+        this.name = "ImmutableFileConflictError";
+    }
+}
+export function openStableDirectory(path, label) {
+    const stablePath = validateExistingDirectory(path, label);
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const directoryOnly = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;
+    const descriptor = openSync(stablePath, constants.O_RDONLY | noFollow | directoryOnly);
+    const opened = fstatSync(descriptor);
+    const entry = lstatSync(stablePath);
+    if (!opened.isDirectory() || opened.dev !== entry.dev || opened.ino !== entry.ino) {
+        closeSync(descriptor);
+        throw new Error(`${label} changed while opening`);
+    }
+    const device = opened.dev;
+    const inode = opened.ino;
+    let closed = false;
+    return {
+        path: stablePath,
+        assertUnchanged() {
+            if (closed)
+                throw new Error(`${label} handle is closed`);
+            const held = fstatSync(descriptor);
+            const currentPath = validateExistingDirectory(stablePath, label);
+            const current = lstatSync(currentPath);
+            if (!held.isDirectory()
+                || held.dev !== device
+                || held.ino !== inode
+                || currentPath !== stablePath
+                || current.dev !== device
+                || current.ino !== inode) {
+                throw new Error(`${label} changed after store creation`);
+            }
+        },
+        close() {
+            if (closed)
+                return;
+            closeSync(descriptor);
+            closed = true;
+        },
+    };
+}
+export function readImmutableFile(path, maxBytes = DEFAULT_MAX_BYTES) {
+    assertMaxBytes(maxBytes);
+    let descriptor;
+    try {
+        const before = lstatSync(path);
+        if (before.isSymbolicLink() || !before.isFile())
+            throw new Error("path is not a regular file");
+        if (before.size > maxBytes)
+            throw new Error(`file exceeds ${maxBytes} bytes`);
+        const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+        descriptor = openSync(path, constants.O_RDONLY | noFollow);
+        const opened = fstatSync(descriptor);
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) {
+            throw new Error("path changed while opening");
+        }
+        if (opened.size > maxBytes)
+            throw new Error(`file exceeds ${maxBytes} bytes`);
+        const bytes = readFileSync(descriptor);
+        if (bytes.byteLength > maxBytes)
+            throw new Error(`file exceeds ${maxBytes} bytes`);
+        closeSync(descriptor);
+        descriptor = undefined;
+        return bytes;
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        throw new Error(`unable to safely read immutable file ${path}: ${errorMessage(error)}`);
+    }
+}
+export function writeImmutableFile(path, bytes) {
+    const temporary = `${path}.tmp.${process.pid}.${randomUUID()}`;
+    let descriptor;
+    let linkingDestination = false;
+    try {
+        descriptor = openSync(temporary, "wx", 0o600);
+        writeFileSync(descriptor, bytes);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        chmodSync(temporary, 0o600);
+        linkingDestination = true;
+        linkSync(temporary, path);
+        linkingDestination = false;
+        fsyncDirectory(dirname(path));
+        let removed = false;
+        try {
+            unlinkSync(temporary);
+            removed = true;
+        }
+        catch {
+            // The immutable destination is committed; a stale temp file is safe to clean later.
+        }
+        if (removed)
+            fsyncDirectory(dirname(path));
+        return "created";
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The temporary file may not have been created or may already be removed.
+        }
+        if (linkingDestination && isAlreadyExists(error)) {
+            const existing = readImmutableFile(path);
+            if (existing.equals(bytes))
+                return "replayed";
+            throw new ImmutableFileConflictError(path);
+        }
+        throw error;
+    }
+}
+export function assertFileInside(directory, path) {
+    directory.assertUnchanged();
+    if (dirname(path) !== directory.path)
+        throw new Error(`immutable file is outside ${directory.path}`);
+}
+function assertMaxBytes(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error("maxBytes must be a positive integer");
+}
+function isAlreadyExists(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=immutable-file.js.map

package/dist/src/evidence/immutable-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"immutable-file.js","sourceRoot":"","sources":["../../../src/evidence/immutable-file.ts"],"names":[],"mappings":"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"}

package/dist/src/evidence/store.d.ts

@@ -0,0 +1,125 @@
+import { type TicketMaterializer } from "../tickets/materializer.js";
+import { type SyncTicketResult } from "../tickets/store.js";
+import { type ProtectedVerificationRun } from "../verification/protected-runner.js";
+import { type ProtectedGradeSource } from "../verification/grade-source.js";
+import { type ProtectedAdvisorProvenance } from "../dispatch/advice-source.js";
+export type EvidenceKind = "verification-plan" | "executor-result" | "goal-executor-result" | "lease-expiry" | "deterministic-check" | "advisor-output" | "grader-output" | "live-disclosure" | "live-outcome" | "trust-run" | "reflection" | "trust-report";
+export type Slice3EvidenceKind = EvidenceKind;
+export type EvidenceRecord = {
+    schema_version: 1;
+    evidence_id: string;
+    evidence_kind: EvidenceKind;
+    ticket_id: string | null;
+    producer_role: string;
+    created_at: string;
+    payload: Record<string, unknown>;
+};
+export interface EvidenceReference {
+    evidence_id: string;
+    sha256: string;
+    file_name: string;
+}
+export interface EvidenceReader {
+    read(ref: EvidenceReference): EvidenceRecord;
+    references(kind?: EvidenceKind): EvidenceReference[];
+    absolutePath(ref: EvidenceReference): string;
+}
+export interface EvidenceStore extends EvidenceReader {
+    write(record: EvidenceRecord): EvidenceWriteResult;
+}
+export type EvidenceWriteResult = {
+    status: "created" | "replayed";
+    ref: EvidenceReference;
+    record: EvidenceRecord;
+};
+declare const PROTECTED_RESULT_GATE_WRITER: unique symbol;
+declare const PROTECTED_ADVISOR_WRITER: unique symbol;
+export declare function assertEvidenceStore(value: unknown): asserts value is EvidenceStore;
+export declare function registeredEvidenceKinds(): EvidenceKind[];
+export declare function createEvidenceStore(options: {
+    evidenceRoot: string;
+    packageRoot?: string;
+}): EvidenceStore;
+export interface ProtectedResultGateEvidenceWriter {
+    readonly [PROTECTED_RESULT_GATE_WRITER]: true;
+    writeDeterministic(options: {
+        evidenceId: string;
+        createdAt: string;
+        run: ProtectedVerificationRun;
+    }): EvidenceWriteResult;
+    writeGrade(record: EvidenceRecord, source: ProtectedGradeSource): EvidenceWriteResult;
+}
+/** Branded writer used only by the protected verification/result-gate authority. */
+export declare function createProtectedResultGateEvidenceWriter(evidenceStore: EvidenceStore): ProtectedResultGateEvidenceWriter;
+export declare function assertProtectedResultGateEvidenceWriter(value: unknown): asserts value is ProtectedResultGateEvidenceWriter;
+export interface ProtectedAdvisorEvidenceWriter {
+    readonly [PROTECTED_ADVISOR_WRITER]: true;
+    writeAdvice(options: {
+        readonly createdAt: string;
+    }, provenance: ProtectedAdvisorProvenance): EvidenceWriteResult;
+}
+/** Branded writer used only by the protected pre-dispatch advisor authority. */
+export declare function createProtectedAdvisorEvidenceWriter(evidenceStore: EvidenceStore): ProtectedAdvisorEvidenceWriter;
+export declare function assertProtectedAdvisorEvidenceWriter(value: unknown): asserts value is ProtectedAdvisorEvidenceWriter;
+export declare function writeTicketBoundEvidence(options: {
+    evidenceStore: EvidenceStore;
+    ticketMaterializer: TicketMaterializer;
+    record: EvidenceRecord;
+}): EvidenceWriteResult;
+export type GithubProbeCertification = "live" | "non-certifying";
+export interface GithubQueueDisclosure {
+    schema_version: 1;
+    certification: GithubProbeCertification;
+    run_id: string;
+    contact_surface: "github-api-via-gh";
+    expected_spend: "none";
+    operation: "read-ready-issues";
+    repository: string;
+    ready_label: string;
+    issue_limit: number;
+}
+export interface GithubSyncedTicket {
+    ticket_id: string;
+    content_sha256: string;
+    content_file: string;
+    record_version: number;
+    sync_status: "created" | "refreshed" | "unchanged";
+}
+export interface GithubQueueProbeResult {
+    contacted: boolean;
+    disclosure: GithubQueueDisclosure;
+    disclosureEvidence?: EvidenceReference;
+    outcomeEvidence?: EvidenceReference;
+    syncResults: readonly SyncTicketResult[];
+}
+export declare class GithubQueueProbeError extends Error {
+    readonly phase: "contact" | "sync" | "evidence";
+    readonly contacted: boolean;
+    readonly outcomeEvidence?: EvidenceReference;
+    constructor(options: {
+        phase: "contact" | "sync" | "evidence";
+        contacted: boolean;
+        outcomeEvidence?: EvidenceReference;
+        cause: unknown;
+    });
+}
+export interface GithubQueueProbeOptions {
+    runId: string;
+    repository: string;
+    readyLabel?: string;
+    limit?: number;
+    confirmLive: boolean;
+    cwd: string;
+    evidenceStore: EvidenceStore;
+    materializer: TicketMaterializer;
+    emitDisclosure: (disclosure: Readonly<GithubQueueDisclosure>, evidence: Readonly<EvidenceReference>) => void;
+}
+export interface NonCertifyingGithubQueueProbeFixtureOptions extends GithubQueueProbeOptions {
+    env: NodeJS.ProcessEnv;
+}
+/** Certifying path: owns the canonical process, clock, materializer, and evidence writes. */
+export declare function runGithubQueueProbe(options: GithubQueueProbeOptions): GithubQueueProbeResult;
+/** Offline fixture path: still uses runProcess, but every record is permanently non-certifying. */
+export declare function runNonCertifyingGithubQueueProbeFixture(options: NonCertifyingGithubQueueProbeFixtureOptions): GithubQueueProbeResult;
+export declare function sanitizeLiveOutcomeError(value: string): string;
+export {};