@oharness/engine 0.11.0 → 0.14.0

package/dist/runtime-plugins/builtin/dreaming-coordinator.d.ts

@@ -0,0 +1,244 @@
+import type { Message } from "../../core/types.ts";
+import type { DreamNote, DreamOp } from "../../agent/memory-dream.ts";
+import { DreamStore } from "../../agent/memory-ledger.ts";
+import type { AppliedChange, EvidenceSnapshot } from "../../agent/memory-ledger.ts";
+import type { ExtractedSummary } from "../../agent/memory-provider.ts";
+import type { DreamChange, DreamCommitted } from "./memory.ts";
+import type { MemoryScope } from "../../agent/memory-limits.ts";
+import { RoutineLock } from "../../schedule/lock.ts";
+import type { Logger } from "../../util/logger.ts";
+/**
+ * When dreaming happens, for a whole process.
+ *
+ * A local server opens a harness per project, and each has a `dreaming`
+ * plugin. They all register here, so there is one tick, one budget and one
+ * pass over the user's own notes, however many projects are open. Across
+ * processes, a lock file decides which one ticks.
+ *
+ * Each tick, in order: digest due conversations, then dream each scope that
+ * has gathered enough claims and has not dreamed today. A dream writes what
+ * may be applied without asking through memory's commit path, and records the
+ * rest as suggestions for a person.
+ */
+export interface DreamingSettings {
+    /** Whether passes run on their own: always, never, or for paid plans. */
+    auto: boolean | "subscribers";
+    idleHours: number;
+    minUserTurns: number;
+    startDelayMinutes: number;
+    minClaims: number;
+    maxWaitHours: number;
+    maxClaims: number;
+    /** Model tokens a day, estimated at four characters each. */
+    dailyTokens: number;
+}
+export declare const DEFAULT_DREAMING: DreamingSettings;
+export interface DreamSessions {
+    list(): Promise<Array<{
+        id: string;
+        routine?: string;
+        updatedAt: number;
+    }>>;
+    records(id: string): Promise<Array<{
+        message: Message;
+        device: string;
+    }>>;
+    archive(id: string): Promise<Message[]>;
+    /** This machine, as the session store names it in records. */
+    device(): Promise<string>;
+}
+export interface GenerateReply {
+    text: string;
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    costUsd: number;
+}
+/** What one run spent on the model. */
+interface Meter {
+    calls: number;
+    input: number;
+    output: number;
+    costUsd: number;
+    model?: string;
+}
+export interface DreamTarget {
+    /** The project's id. */
+    projectId: string;
+    sessions: DreamSessions;
+    /** Every note in a scope, as the dream sees it; absent when the scope is. */
+    notes(scope: MemoryScope): Promise<DreamNote[] | undefined>;
+    /** One reply from the small model, with what it cost. */
+    generate(system: string, prompt: string, signal?: AbortSignal): Promise<GenerateReply>;
+    settings(): DreamingSettings;
+    /** Whether automatic passes are on now (settings and plan together). */
+    autoOn(): boolean;
+    /** Write changes to one scope through memory, as one batch. */
+    commit(scope: MemoryScope, changes: readonly DreamChange[]): Promise<DreamCommitted[]>;
+    /** Tell the next run in this project what changed. */
+    announce(notes: ExtractedSummary[]): void;
+}
+/** What one dream of one scope did. */
+export interface ScopeRun {
+    scope: MemoryScope;
+    claims: number;
+    applied: AppliedChange[];
+    proposals: number;
+    /** Set when the batch was refused (stale) or the model call failed. */
+    error?: string;
+    /** The batch was refused: another edit came first. */
+    refused?: boolean;
+}
+export interface DreamRun {
+    id: string;
+    at: number;
+    digested: number;
+    scopes: ScopeRun[];
+    meter: Meter;
+    /** Set when the day's budget stopped the run part way. */
+    budgetStopped?: boolean;
+}
+/** The suggestions and log of one scope, as the page shows them. */
+export interface ScopeState {
+    proposals: Array<{
+        id: string;
+        scope: MemoryScope;
+        at: number;
+        op: DreamOp;
+        why?: string;
+        evidence: EvidenceSnapshot[];
+    }>;
+    log: Array<{
+        scope: MemoryScope;
+        at: number;
+        change: AppliedChange;
+        undone: boolean;
+    }>;
+}
+export declare const projectLedgerKey: (projectId: string) => string;
+export declare const USER_LEDGER_KEY = "user";
+export declare class DreamCoordinator {
+    /** The process's coordinator. Tests construct their own. */
+    static readonly shared: DreamCoordinator;
+    readonly store: DreamStore;
+    private readonly targets;
+    private readonly fixedLock?;
+    private homeLock?;
+    private readonly now;
+    private logger?;
+    private startedAt;
+    private lastActivity;
+    private timer?;
+    private running?;
+    private readonly runs;
+    constructor(options?: {
+        store?: DreamStore;
+        lock?: RoutineLock;
+        now?: () => number;
+    });
+    /** Resolved on use, like the store, so a changed `OHARNESS_HOME` is honoured. */
+    private get lock();
+    register(target: DreamTarget, logger?: Logger): () => void;
+    /** Someone is sending a message or a run just ended: background work waits. */
+    activity(): void;
+    lastRun(target: DreamTarget): DreamRun | undefined;
+    isRunning(): boolean;
+    private schedule;
+    /** One work item at a time, whether a tick or a person's request. */
+    private exclusive;
+    /**
+     * The background pass: digest every due session of every project whose
+     * automatic passes are on. Waits while a run is in progress or another
+     * process holds the lock.
+     */
+    tick(signal?: AbortSignal): Promise<{
+        digested: number;
+        dreamed: number;
+        skipped?: "busy" | "locked";
+    }>;
+    private key;
+    private claimsOf;
+    /**
+     * Whether a scope dreams this tick: not yet today (a local calendar day, not
+     * a rolling 24 hours, which would drift into the working morning), and
+     * enough claims gathered, or the oldest waiting long enough.
+     */
+    private due;
+    /** Whether a prompt of `chars` characters may still be sent today. */
+    private affordable;
+    /**
+     * The model, as a dream or a digest calls it: the reply's text, with what it
+     * cost added to the run and to the day's budget, in the tokens the provider
+     * reported.
+     */
+    private metered;
+    private newRun;
+    /** Write a run to the project's history. */
+    private finish;
+    /**
+     * Digest a project's sessions. Unforced, only sessions quiet for
+     * `idleHours` with `minUserTurns` new user messages; forced (Dream now),
+     * every session with anything new the user typed.
+     */
+    digestTarget(target: DreamTarget, options: {
+        force: boolean;
+        meter?: Meter;
+        signal?: AbortSignal;
+    }): Promise<{
+        digested: number;
+        budgetStopped?: boolean;
+        more?: boolean;
+    }>;
+    /**
+     * Dream now: read everything new, however recently said, then dream both
+     * scopes regardless of the day or the batch threshold.
+     */
+    dreamNow(target: DreamTarget, signal?: AbortSignal): Promise<DreamRun>;
+    /** Hashes dreams last left notes at, from the ledger, for the hand-edit rule. */
+    private dreamWrote;
+    /**
+     * One dream of one scope: claims in, changes out. What may be applied is
+     * committed as one batch; the rest becomes suggestions. The day is marked
+     * whether or not the batch lands, so a refused batch is not retried every
+     * tick at the price of a model call; the claims behind it stay for the next
+     * dream instead of being consumed.
+     */
+    private dreamScope;
+    /** Commit operations as one batch, record them, and tell the next run. */
+    private commitOps;
+    /** Open suggestions and recent changes, both scopes, newest first. */
+    state(target: DreamTarget): Promise<ScopeState>;
+    private proposal;
+    /** A person applies a suggestion; refused, and closed as stale, if its notes changed since. */
+    applyProposal(target: DreamTarget, scope: MemoryScope, id: string): Promise<AppliedChange[]>;
+    dismissProposal(target: DreamTarget, scope: MemoryScope, id: string): Promise<void>;
+    /**
+     * Put back what a change replaced. Refused if any of its notes changed
+     * since, rather than overwriting someone's newer edit; the page then points
+     * at the backups.
+     */
+    undo(target: DreamTarget, scope: MemoryScope, changeId: string): Promise<void>;
+    /**
+     * What decides the next automatic dream, per scope, for the page: whether it
+     * already dreamed today, and how many claims wait and since when.
+     */
+    nextDream(target: DreamTarget): Promise<{
+        spentToday: number;
+        scopes: Array<{
+            scope: MemoryScope;
+            dreamedToday: boolean;
+            waiting: number;
+            oldestAt?: number;
+        }>;
+    }>;
+    /** Claims waiting, per scope, for the page. */
+    pending(target: DreamTarget): Promise<{
+        project: number;
+        user: number;
+    }>;
+}
+export {};