@cybernetyx1/atlasflow-runtime 0.1.0

package/dist/index-UFTgKRK4.d.ts

@@ -0,0 +1,589 @@
+/**
+ * AtlasFlow public domain types.
+ *
+ * Independent of any underlying model/provider library. The engine adapter
+ * (engine-pi.ts) maps between these and pi-ai today; swapping in our own
+ * agentic loop later only touches the adapter, not these types.
+ */
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/** A model reference: "<provider>/<model-id>", e.g. "anthropic/claude-sonnet-4-6". */
+type ModelConfig = string;
+type CacheRetention = "none" | "short" | "long";
+interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    costTotal: number;
+}
+declare function emptyUsage(): Usage;
+declare function addUsage(a: Usage, b: Usage): Usage;
+interface TextPart {
+    type: "text";
+    text: string;
+}
+interface ThinkingPart {
+    type: "thinking";
+    thinking: string;
+}
+interface ImagePart {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+interface ToolCallPart {
+    type: "tool_call";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+type AssistantPart = TextPart | ThinkingPart | ToolCallPart;
+type UserPart = TextPart | ImagePart;
+interface UserMessage {
+    role: "user";
+    content: UserPart[];
+}
+interface AssistantMessage {
+    role: "assistant";
+    content: AssistantPart[];
+    usage: Usage;
+    stopReason: StopReason;
+}
+interface ToolResultMessage {
+    role: "tool_result";
+    toolCallId: string;
+    toolName: string;
+    content: (TextPart | ImagePart)[];
+    isError?: boolean;
+}
+type Message = UserMessage | AssistantMessage | ToolResultMessage;
+type StopReason = "stop" | "length" | "tool_use" | "error" | "aborted";
+interface PromptImage {
+    data: string;
+    mimeType: string;
+}
+
+/**
+ * AtlasFlow event stream.
+ *
+ * Design note: a strict discriminated union where each event
+ * type carries exactly the fields it needs — no "optional fields that are
+ * actually required". Consumers switch on `type` with full type-narrowing.
+ */
+
+interface EventBase {
+    index: number;
+    timestamp: number;
+    runId?: string;
+    session?: string;
+}
+type AtlasEvent = (EventBase & {
+    type: "run_queued";
+    agent: string;
+    instanceId: string;
+}) | (EventBase & {
+    type: "run_start";
+    agent: string;
+    instanceId: string;
+}) | (EventBase & {
+    type: "run_resume";
+    agent: string;
+    instanceId: string;
+}) | (EventBase & {
+    type: "run_end";
+    ok: boolean;
+}) | (EventBase & {
+    type: "run_error";
+    code: string;
+    message: string;
+}) | (EventBase & {
+    type: "agent_start";
+    agent: string;
+}) | (EventBase & {
+    type: "agent_end";
+}) | (EventBase & {
+    type: "operation_start";
+    operationId: string;
+    kind: OperationKind;
+}) | (EventBase & {
+    type: "operation_end";
+    operationId: string;
+    ok: boolean;
+}) | (EventBase & {
+    type: "turn_start";
+    turnId: string;
+    model: string;
+}) | (EventBase & {
+    type: "turn_end";
+    turnId: string;
+    usage: Usage;
+    stopReason: string;
+}) | (EventBase & {
+    type: "text_delta";
+    turnId: string;
+    delta: string;
+}) | (EventBase & {
+    type: "thinking_delta";
+    turnId: string;
+    delta: string;
+}) | (EventBase & {
+    type: "tool_call";
+    tool: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+}) | (EventBase & {
+    type: "tool_approval_requested";
+    approval: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+}) | (EventBase & {
+    type: "tool_approval_decided";
+    approval: string;
+    tool: string;
+    approved: boolean;
+}) | (EventBase & {
+    type: "tool_result";
+    tool: string;
+    callId: string;
+    ok: boolean;
+}) | (EventBase & {
+    type: "task_start";
+    taskId: string;
+    agent: string;
+}) | (EventBase & {
+    type: "task_end";
+    taskId: string;
+    ok: boolean;
+}) | (EventBase & {
+    type: "compaction";
+    freedTokens: number;
+}) | (EventBase & {
+    type: "rule_triggered";
+    rule: string;
+    point: string;
+    action: "block" | "warn";
+}) | (EventBase & {
+    type: "message";
+    text: string;
+}) | (EventBase & {
+    type: "log";
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+});
+type OperationKind = "prompt" | "skill" | "task" | "shell" | "compact";
+type EventSubscriber = (event: AtlasEvent) => void;
+/** Distributive Omit so union members keep their own discriminant fields. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** An event as emitted (index/timestamp injected by the bus). */
+type EmittedEvent = DistributiveOmit<AtlasEvent, "index" | "timestamp"> & Partial<EventBase>;
+declare class EventBus {
+    #private;
+    /**
+     * `startIndex` seeds event numbering. Recovery re-invokes a run with the same
+     * runId; seeding with the persisted event count keeps the per-run event log
+     * append-only instead of colliding with (or overwriting) attempt one.
+     */
+    constructor(startIndex?: number);
+    subscribe(fn: EventSubscriber): () => void;
+    emit(event: EmittedEvent): void;
+}
+declare function observe(fn: EventSubscriber): () => void;
+
+/**
+ * Persistence interfaces + the zero-config in-memory adapter.
+ *
+ * Design note: a real in-memory adapter is the default, so
+ * `atlasflow dev` and tests need no database. Durable adapters (sqlite,
+ * postgres, Cloudflare DO) implement the same PersistenceAdapter.
+ */
+
+interface SessionData {
+    name: string;
+    messages: Message[];
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionStore {
+    get(key: string): Promise<SessionData | null>;
+    put(key: string, data: SessionData): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+type RunStatus = "queued" | "running" | "waiting_approval" | "success" | "failed" | "interrupted";
+interface RunRecord {
+    runId: string;
+    agent: string;
+    instanceId: string;
+    status: RunStatus;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+    startedAt: number;
+    endedAt?: number;
+    /** Stored input so an interrupted run can be replayed on recovery. */
+    message?: string;
+    payload?: unknown;
+    images?: PromptImage[];
+    /** "agent" (default) or "workflow" (an authored, gated process). */
+    kind?: "agent" | "workflow";
+    /** Executor state for workflow runs: cursor, step results, gate decisions. */
+    state?: unknown;
+    /** Current execution owner. Recovery must not re-dispatch while this lease is live. */
+    leaseOwner?: string;
+    leaseExpiresAt?: number;
+    leaseAcquiredAt?: number;
+}
+interface RunStore {
+    create(record: RunRecord): Promise<void>;
+    update(runId: string, patch: Partial<RunRecord>): Promise<void>;
+    get(runId: string): Promise<RunRecord | null>;
+    list(filter?: {
+        status?: RunStatus;
+        agent?: string;
+        limit?: number;
+    }): Promise<RunRecord[]>;
+    /**
+     * Claim a queued run for execution. This is the durable submission boundary:
+     * admission writes `queued`, workers atomically transition to `running`.
+     */
+    claimQueued(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    /**
+     * Claim a running run for execution/recovery. Returns false when another
+     * live owner still holds the lease or the run is no longer running.
+     */
+    claimLease(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    /** Extend a live lease. Returns false when the caller no longer owns it. */
+    heartbeatLease(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    /** Clear the lease if it is still owned by the caller. */
+    releaseLease(runId: string, owner: string): Promise<void>;
+    appendEvent(runId: string, event: AtlasEvent): Promise<void>;
+    events(runId: string): Promise<AtlasEvent[]>;
+    /** Number of persisted events for a run (used to seed indices on recovery). */
+    eventCount?(runId: string): Promise<number>;
+}
+interface PersistenceAdapter {
+    sessions: SessionStore;
+    runs: RunStore;
+    streams: StreamStore;
+    subscriptions?: SubscriptionStore;
+}
+interface PersistenceAdapterOptions {
+    webhooks?: WebhookDeliveryOptions;
+}
+interface DurableStreamRecord {
+    path: string;
+    contentType: string;
+    closed: boolean;
+    currentOffset: string;
+    lastSeq?: string;
+    createdAt: number;
+    updatedAt: number;
+    ttlSeconds?: number;
+    expiresAt?: string;
+    producers?: Record<string, DurableStreamProducerState>;
+    closedBy?: DurableStreamProducerTuple;
+}
+interface DurableStreamMessage {
+    index: number;
+    offset: string;
+    dataBase64: string;
+    createdAt: number;
+}
+interface DurableStreamProducerState {
+    epoch: number;
+    lastSeq: number;
+    lastUpdated: number;
+}
+interface DurableStreamProducerTuple {
+    producerId: string;
+    epoch: number;
+    seq: number;
+}
+type StreamProducerResult = {
+    status: "accepted";
+    isNew: boolean;
+    producerId: string;
+    proposedState: DurableStreamProducerState;
+} | {
+    status: "duplicate";
+    lastSeq: number;
+} | {
+    status: "stale_epoch";
+    currentEpoch: number;
+} | {
+    status: "invalid_epoch_seq";
+} | {
+    status: "sequence_gap";
+    expectedSeq: number;
+    receivedSeq: number;
+} | {
+    status: "stream_closed";
+};
+interface StreamStore {
+    create(path: string, opts?: StreamCreateOptions): Promise<{
+        record: DurableStreamRecord;
+        created: boolean;
+    }>;
+    get(path: string): Promise<DurableStreamRecord | null>;
+    delete(path: string): Promise<boolean>;
+    append(path: string, data: Uint8Array, opts: StreamAppendOptions): Promise<{
+        record: DurableStreamRecord;
+        message: DurableStreamMessage;
+    } | null>;
+    appendWithProducer(path: string, data: Uint8Array, opts: StreamAppendOptions & {
+        producer: DurableStreamProducerTuple;
+    }): Promise<StreamProducerAppendResult | null>;
+    close(path: string): Promise<DurableStreamRecord | null>;
+    closeWithProducer(path: string, producer: DurableStreamProducerTuple): Promise<StreamProducerCloseResult | null>;
+    messages(path: string): Promise<DurableStreamMessage[]>;
+    list?(): Promise<string[]>;
+}
+interface StreamProducerAppendResult {
+    record: DurableStreamRecord;
+    message: DurableStreamMessage | null;
+    producerResult?: StreamProducerResult;
+    streamClosed?: boolean;
+}
+interface StreamProducerCloseResult {
+    record: DurableStreamRecord;
+    producerResult?: StreamProducerResult;
+    alreadyClosed: boolean;
+}
+interface StreamCreateOptions {
+    contentType?: string;
+    ttlSeconds?: number;
+    expiresAt?: string;
+    initialData?: Uint8Array;
+    closed?: boolean;
+    fork?: {
+        path: string;
+        offset?: string;
+    };
+}
+interface StreamAppendOptions {
+    contentType: string;
+    close?: boolean;
+    seq?: string;
+}
+type DurableStreamSubscriptionType = "pull-wake" | "webhook";
+type DurableStreamSubscriptionStatus = "active";
+type DurableStreamSubscriptionLinkType = "explicit" | "glob";
+type DurableStreamSubscriptionErrorCode = "INVALID_REQUEST" | "SUBSCRIPTION_NOT_FOUND" | "SUBSCRIPTION_ALREADY_EXISTS" | "TOKEN_INVALID" | "FENCED" | "ALREADY_CLAIMED" | "NO_PENDING_WORK" | "INVALID_OFFSET";
+interface DurableStreamSubscriptionLink {
+    path: string;
+    linkTypes: DurableStreamSubscriptionLinkType[];
+    ackedOffset: string;
+}
+interface DurableStreamSubscriptionRecord {
+    id: string;
+    type: DurableStreamSubscriptionType;
+    pattern?: string;
+    streams: DurableStreamSubscriptionLink[];
+    wakeStream?: string;
+    leaseTtlMs?: number;
+    webhookUrl?: string;
+    webhookHeaders?: Record<string, string>;
+    webhookLastSuccessAt?: string;
+    webhookLastError?: string;
+    description?: string;
+    createdAt: string;
+    status: DurableStreamSubscriptionStatus;
+    configHash: string;
+    generation: number;
+    wakeId?: string;
+    wakeSnapshot?: Record<string, string>;
+    token?: string;
+    holder?: string;
+    leaseExpiresAt?: number;
+}
+interface DurableStreamSubscriptionCreateInput {
+    type: DurableStreamSubscriptionType;
+    pattern?: string;
+    streams: string[];
+    wakeStream?: string;
+    leaseTtlMs?: number;
+    webhookUrl?: string;
+    webhookHeaders?: Record<string, string>;
+    description?: string;
+}
+interface DurableStreamSubscriptionAckInput {
+    wakeId?: string;
+    generation?: number;
+    acks?: Array<{
+        stream?: string;
+        path?: string;
+        offset: string;
+    }>;
+    done?: boolean;
+}
+interface DurableStreamSubscriptionStreamInfo {
+    path: string;
+    linkType: DurableStreamSubscriptionLinkType;
+    ackedOffset: string;
+    tailOffset: string;
+    hasPending: boolean;
+}
+interface DurableStreamSubscriptionError {
+    code: DurableStreamSubscriptionErrorCode;
+    message: string;
+    currentHolder?: string;
+    generation?: number;
+}
+interface DurableStreamSubscriptionClaim {
+    wakeId: string;
+    generation: number;
+    token: string;
+    streams: DurableStreamSubscriptionStreamInfo[];
+    leaseTtlMs: number;
+}
+interface DurableStreamSubscriptionAckResult {
+    ok: true;
+    nextWake: boolean;
+}
+type DurableStreamSubscriptionResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    status: number;
+    error: DurableStreamSubscriptionError;
+};
+interface SubscriptionStore {
+    createOrConfirm(id: string, input: DurableStreamSubscriptionCreateInput): Promise<DurableStreamSubscriptionResult<{
+        subscription: DurableStreamSubscriptionRecord;
+        created: boolean;
+    }>>;
+    get(id: string): Promise<DurableStreamSubscriptionRecord | null>;
+    delete(id: string): Promise<boolean>;
+    addExplicitStreams(id: string, streams: string[]): Promise<boolean>;
+    removeExplicitStream(id: string, streamPath: string): Promise<boolean>;
+    notifyStreamAppend(streamPath: string, message?: DurableStreamMessage): Promise<void>;
+    notifyStreamDelete(streamPath: string): Promise<void>;
+    claim(id: string, worker: string): Promise<DurableStreamSubscriptionResult<DurableStreamSubscriptionClaim>>;
+    ack(id: string, token: string, input: DurableStreamSubscriptionAckInput): Promise<DurableStreamSubscriptionResult<DurableStreamSubscriptionAckResult>>;
+    release(id: string, token: string, input: DurableStreamSubscriptionAckInput): Promise<DurableStreamSubscriptionResult<void>>;
+    streamInfos(subscription: DurableStreamSubscriptionRecord): Promise<DurableStreamSubscriptionStreamInfo[]>;
+}
+interface WebhookDeliveryOptions {
+    /** Test/dev escape hatch. Production defaults block localhost, private IPs, and plain HTTP. */
+    allowUnsafeWebhookUrls?: boolean;
+    /** Test/dev escape hatch. Production defaults reject authorization/cookie-style callback headers. */
+    allowSensitiveWebhookHeaders?: boolean;
+    /** Optional production allowlist. Entries are exact hosts or wildcard suffixes such as "*.example.com". */
+    allowedWebhookHosts?: string[];
+    /** Override DNS resolution for tests or custom runtimes. Defaults to DNS-over-HTTPS. */
+    resolveWebhookHost?: WebhookHostResolver | false;
+    dnsTimeoutMs?: number;
+}
+type WebhookHostResolver = (hostname: string) => Promise<string[]>;
+declare class InMemorySessionStore implements SessionStore {
+    #private;
+    get(key: string): Promise<SessionData | null>;
+    put(key: string, data: SessionData): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class InMemoryRunStore implements RunStore {
+    #private;
+    create(record: RunRecord): Promise<void>;
+    update(runId: string, patch: Partial<RunRecord>): Promise<void>;
+    get(runId: string): Promise<RunRecord | null>;
+    list(filter?: {
+        status?: RunStatus;
+        agent?: string;
+        limit?: number;
+    }): Promise<RunRecord[]>;
+    claimLease(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    claimQueued(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    heartbeatLease(runId: string, owner: string, now: number, ttlMs: number): Promise<boolean>;
+    releaseLease(runId: string, owner: string): Promise<void>;
+    appendEvent(runId: string, event: AtlasEvent): Promise<void>;
+    events(runId: string): Promise<AtlasEvent[]>;
+    eventCount(runId: string): Promise<number>;
+}
+declare class InMemoryStreamStore implements StreamStore {
+    #private;
+    create(path: string, opts?: StreamCreateOptions): Promise<{
+        record: DurableStreamRecord;
+        created: boolean;
+    }>;
+    get(path: string): Promise<DurableStreamRecord | null>;
+    delete(path: string): Promise<boolean>;
+    append(path: string, data: Uint8Array, opts: StreamAppendOptions): Promise<{
+        record: DurableStreamRecord;
+        message: DurableStreamMessage;
+    } | null>;
+    appendWithProducer(path: string, data: Uint8Array, opts: StreamAppendOptions & {
+        producer: DurableStreamProducerTuple;
+    }): Promise<StreamProducerAppendResult | null>;
+    close(path: string): Promise<DurableStreamRecord | null>;
+    closeWithProducer(path: string, producer: DurableStreamProducerTuple): Promise<StreamProducerCloseResult | null>;
+    messages(path: string): Promise<DurableStreamMessage[]>;
+    list(): Promise<string[]>;
+}
+declare abstract class DurableStreamSubscriptionStoreBase implements SubscriptionStore {
+    private readonly streams;
+    private readonly deliveryFetch;
+    private readonly webhookOptions;
+    constructor(streams: StreamStore, deliveryFetch?: typeof fetch, webhookOptions?: WebhookDeliveryOptions);
+    protected abstract load(id: string): Promise<DurableStreamSubscriptionRecord | null>;
+    protected abstract save(record: DurableStreamSubscriptionRecord): Promise<void>;
+    protected abstract remove(id: string): Promise<boolean>;
+    protected abstract listRecords(): Promise<DurableStreamSubscriptionRecord[]>;
+    createOrConfirm(id: string, input: DurableStreamSubscriptionCreateInput): Promise<DurableStreamSubscriptionResult<{
+        subscription: DurableStreamSubscriptionRecord;
+        created: boolean;
+    }>>;
+    get(id: string): Promise<DurableStreamSubscriptionRecord | null>;
+    delete(id: string): Promise<boolean>;
+    addExplicitStreams(id: string, streams: string[]): Promise<boolean>;
+    removeExplicitStream(id: string, streamPath: string): Promise<boolean>;
+    notifyStreamAppend(streamPath: string, message?: DurableStreamMessage): Promise<void>;
+    notifyStreamDelete(streamPath: string): Promise<void>;
+    claim(id: string, worker: string): Promise<DurableStreamSubscriptionResult<DurableStreamSubscriptionClaim>>;
+    ack(id: string, token: string, input: DurableStreamSubscriptionAckInput): Promise<DurableStreamSubscriptionResult<DurableStreamSubscriptionAckResult>>;
+    release(id: string, token: string, input: DurableStreamSubscriptionAckInput): Promise<DurableStreamSubscriptionResult<void>>;
+    streamInfos(subscription: DurableStreamSubscriptionRecord): Promise<DurableStreamSubscriptionStreamInfo[]>;
+    private linkStream;
+    private createWakeIfPending;
+    private createWake;
+    private writeWakeEvent;
+    private hasPendingWork;
+    private firstPendingStream;
+    private validateWakeToken;
+    private applyAcks;
+    private clearLease;
+    private clearExpiredLease;
+    private listStreamPaths;
+    private tailOffset;
+    private deliverWebhookPending;
+    private deliverWebhookAppend;
+    private deliverWebhookDelete;
+    private postWebhook;
+}
+declare class InMemorySubscriptionStore extends DurableStreamSubscriptionStoreBase {
+    #private;
+    constructor(streams: StreamStore, deliveryFetch?: typeof fetch, webhookOptions?: WebhookDeliveryOptions);
+    protected load(id: string): Promise<DurableStreamSubscriptionRecord | null>;
+    protected save(record: DurableStreamSubscriptionRecord): Promise<void>;
+    protected remove(id: string): Promise<boolean>;
+    protected listRecords(): Promise<DurableStreamSubscriptionRecord[]>;
+}
+declare function inMemoryAdapter(options?: PersistenceAdapterOptions): PersistenceAdapter;
+/** Minimal key/value contract — Cloudflare DurableObjectStorage satisfies this. */
+interface KvLike {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<unknown>;
+    list<T = unknown>(options: {
+        prefix: string;
+    }): Promise<Map<string, T>>;
+}
+declare function kvAdapter(kv: KvLike, options?: PersistenceAdapterOptions): PersistenceAdapter;
+declare function normalizeStreamContentType(value: string | undefined): string;
+declare function isJsonStreamContentType(contentType: string): boolean;
+declare function streamMessageBytes(message: DurableStreamMessage): Uint8Array;
+
+export { emptyUsage as $, type AtlasEvent as A, InMemorySessionStore as B, type CacheRetention as C, type DurableStreamRecord as D, EventBus as E, InMemoryStreamStore as F, InMemorySubscriptionStore as G, type PersistenceAdapterOptions as H, InMemoryRunStore as I, type RunStore as J, type KvLike as K, type StopReason as L, type ModelConfig as M, type StreamProducerResult as N, type OperationKind as O, type PersistenceAdapter as P, type StreamStore as Q, type RunRecord as R, type SessionData as S, type ThinkingLevel as T, type Usage as U, type SubscriptionStore as V, type ToolResultMessage as W, type UserMessage as X, type WebhookDeliveryOptions as Y, type WebhookHostResolver as Z, addUsage as _, type RunStatus as a, inMemoryAdapter as a0, isJsonStreamContentType as a1, kvAdapter as a2, normalizeStreamContentType as a3, observe as a4, streamMessageBytes as a5, type StreamCreateOptions as b, type StreamAppendOptions as c, type DurableStreamMessage as d, type DurableStreamProducerTuple as e, type StreamProducerAppendResult as f, type StreamProducerCloseResult as g, type DurableStreamSubscriptionCreateInput as h, type DurableStreamSubscriptionResult as i, type DurableStreamSubscriptionRecord as j, type DurableStreamSubscriptionClaim as k, type DurableStreamSubscriptionAckInput as l, type DurableStreamSubscriptionStreamInfo as m, type Message as n, type PromptImage as o, type SessionStore as p, type AssistantMessage as q, type DurableStreamProducerState as r, type DurableStreamSubscriptionError as s, type DurableStreamSubscriptionErrorCode as t, type DurableStreamSubscriptionLink as u, type DurableStreamSubscriptionLinkType as v, type DurableStreamSubscriptionStatus as w, DurableStreamSubscriptionStoreBase as x, type DurableStreamSubscriptionType as y, type EventSubscriber as z };