@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/journal/journal.ts

@@ -49,7 +49,12 @@ const parseLine = ({
     return parsed.data
 }
 
-const readRecords = ({ file }: { file: string }): JournalRecord[] => {
+/**
+ * Reads and checks every record of the journal at `file`, oldest first,
+ * without opening it for appends: none when it has no file. Throws on a
+ * line that isn't a record.
+ */
+export const readRecords = ({ file }: { file: string }): JournalRecord[] => {
     if (!existsSync(file)) return []
     return readFileSync(file, 'utf8')
         .split('\n')

package/engine/journal/limit-entries.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+import { AgentRoleSchema } from '../agents/role-results'
+import { UsageRecordSchema } from '../limits/plan-usage'
+
+/**
+ * The journal entries of plan limits: limit waits, usage-line waits, and
+ * recorded plan usage.
+ */
+
+/**
+ * A plan window was used up (a rejected rate limit), so the whole run waits
+ * until `until`: the window's reset plus a margin, or a default wait when the
+ * reading named no reset. Written with `ticket: null`; the agent whose turn
+ * hit the limit is `hit_ticket` and `hit_role`.
+ */
+export const LimitWaitStartedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('limit_wait_started'),
+    content: z.object({
+        /** When the window resets, if the reading said. */
+        resets_at: z.iso.datetime().nullable(),
+        /** When the engine wakes and carries on. */
+        until: z.iso.datetime(),
+        /** The window, such as `five_hour`, `seven_day`, or `seven_day_opus`. */
+        rate_limit_type: z.string().nullable(),
+        hit_ticket: z.number().int().positive().nullable(),
+        hit_role: AgentRoleSchema.nullable(),
+    }),
+})
+
+/** The limit wait is over; the run carries on where it was cut off. */
+export const LimitWaitEndedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('limit_wait_ended'),
+    content: z.object({ until: z.iso.datetime() }),
+})
+
+/** The plan windows a usage line guards: all-models weekly, and 5-hour. */
+export const UsageLineWindowSchema = z.enum(['seven_day', 'five_hour'])
+
+export type UsageLineWindow = z.infer<typeof UsageLineWindowSchema>
+
+/**
+ * The newest plan-window reading was at or over its **usage line**, so the
+ * whole run pauses until `until`: the window's reset plus a margin. The wait
+ * ends sooner once the line is raised above `percent`.
+ */
+export const UsageLineWaitStartedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('usage_line_wait_started'),
+    content: z.object({
+        window: UsageLineWindowSchema,
+        /** The line, in percent of the window. */
+        line: z.number(),
+        /** The reading's fill level, in percent. */
+        percent: z.number(),
+        /** When the window resets. */
+        resets_at: z.iso.datetime(),
+        /** When the engine wakes and carries on, at the latest. */
+        until: z.iso.datetime(),
+    }),
+})
+
+/**
+ * The usage-line wait is over: the window reset (`reset`), or the line was
+ * raised above the reading (`line_raised`).
+ */
+export const UsageLineWaitEndedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('usage_line_wait_ended'),
+    content: z.object({
+        until: z.iso.datetime(),
+        reason: z.enum(['reset', 'line_raised']),
+    }),
+})
+
+/**
+ * The plan usage of one ticket (when it was pushed, or got stuck) or of the
+ * whole run (when it ended): tokens from its agent sessions, and how far
+ * each plan window moved. A retried ticket that finishes again gets another,
+ * over all of its sessions: the latest is its whole usage.
+ */
+export const UsageRecordedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('usage_recorded'),
+    content: UsageRecordSchema,
+})

package/engine/journal/memory-entries.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+import {
+    MemoryFeedbackSchema,
+    MemorySaveSchema,
+    RecalledMemorySchema,
+    RecallPointSchema,
+    VaultSearchSchema,
+} from '../memory/memory-schemas'
+
+/**
+ * The journal entries of memory (#370): recalls, the learner's saves and
+ * feedback, each MuninnDB write, and a skipped or reported learning.
+ */
+
+/**
+ * The engine searched memory at a **recall point**: the vaults it searched
+ * (each with how it went and how many it found), and the memories it will
+ * show, merged by score, at most `MAX_MEMORIES_PER_RECALL`, each with its
+ * vault and score. `key` names the moment (such as `ticket:11`), so each is
+ * searched once. `ticket` is the ticket's, or `null` for the run's start
+ * and the final review.
+ */
+export const MemoryRecalledEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('memory_recalled'),
+    content: z.object({
+        point: RecallPointSchema,
+        key: z.string().min(1),
+        query: z.string(),
+        vaults: z.array(VaultSearchSchema),
+        memories: z.array(RecalledMemorySchema),
+    }),
+})
+
+/**
+ * The learner's proposed memories were saved (or refused, or failed), each
+ * with its vault, what became of it, and the similar memory the engine
+ * found first; then the helped / didn't-help feedback on each memory shown
+ * in the run. Written once per run, with `ticket: null`.
+ */
+export const MemoriesSavedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('memories_saved'),
+    content: z.object({
+        saves: z.array(MemorySaveSchema),
+        feedback: z.array(MemoryFeedbackSchema),
+    }),
+})
+
+/**
+ * The engine is about to make one MuninnDB write of `save_memories` (#369):
+ * a save (`update_id` names the similar memory it updates, `muninn_evolve`;
+ * `null` adds a new one, `muninn_remember` with `op_id`) or a feedback on a
+ * shown memory. `write_key` names it within its step: `save:<op_id>` or
+ * `feedback:<vault>:<id>`. A redo of the step repeats a save started but
+ * not done the same way, and never sends such a feedback again.
+ */
+export const MemoryWriteStartedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('memory_write_started'),
+    content: z.discriminatedUnion('what', [
+        z.object({
+            write_key: z.string().min(1),
+            what: z.literal('save'),
+            vault: z.string().min(1),
+            concept: z.string(),
+            op_id: z.string().min(1),
+            update_id: z.string().nullable(),
+            similar: MemorySaveSchema.shape.similar,
+        }),
+        z.object({
+            write_key: z.string().min(1),
+            what: z.literal('feedback'),
+            vault: z.string().min(1),
+            id: z.string().min(1),
+            useful: z.boolean(),
+        }),
+    ]),
+})
+
+/**
+ * One MuninnDB write of `save_memories` settled (or a save failed before
+ * its write): its outcome, which a redo of the step reuses as it is. Its
+ * step's `memories_saved` lists them all.
+ */
+export const MemoryWriteDoneEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('memory_write_done'),
+    content: z.discriminatedUnion('what', [
+        z.object({
+            write_key: z.string().min(1),
+            what: z.literal('save'),
+            save: MemorySaveSchema,
+        }),
+        z.object({
+            write_key: z.string().min(1),
+            what: z.literal('feedback'),
+            feedback: MemoryFeedbackSchema,
+        }),
+    ]),
+})
+
+/** The learner never gave a usable answer; the run ends without it. */
+export const LearningSkippedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('learning_skipped'),
+    content: z.object({ reason: z.string() }),
+})
+
+/**
+ * With no PR to list them in, the new memories went on the spec issue in
+ * the engine's comment `comment_id`.
+ */
+export const MemoriesReportedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('memories_reported'),
+    content: z.object({
+        comment_id: z.number().int(),
+        count: z.number().int().min(0),
+    }),
+})

package/engine/journal/memory-replay.ts

@@ -0,0 +1,157 @@
+/**
+ * Memory as replay rebuilds it (#370): its state shape, a run with memory
+ * off, and the learner's own agent records.
+ */
+import { ranCheaper } from './agent-turn-replay'
+import type { ReplayedAgentFailure } from './final-review-state'
+import type { JournalRecord } from './journal-record'
+
+import type { LearnerResult } from '../agents/role-results'
+import type {
+    MemoryFeedback,
+    MemorySave,
+    RecallPoint,
+    RecalledMemory,
+} from '../memory/memory-schemas'
+
+/**
+ * The learner at the end of a run (#370): its answer, or its failed tries,
+ * or that the engine gave up on it. Learner records have `ticket: null` and
+ * role `learner`; they never count as the final review's.
+ */
+export type LearnerState = {
+    /** Its result, once it finished. */
+    result: LearnerResult | null
+    /** The seq of its `agent_finished`, for the saves' op ids. */
+    result_seq: number | null
+    /** Its latest failed turn, if none finished after it. */
+    agent_failure: ReplayedAgentFailure | null
+    /** Failed tries (agent, result, guard), in all. */
+    failed_tries: number
+    /** The model its latest agent launched on (#604); `null` in older journals. */
+    launched_on: string | null
+    /**
+     * It used up a try on a model cheaper than Opus (#604), so its later
+     * agents run Opus.
+     */
+    failed_cheaper: boolean
+    /** Engine failures in a row. */
+    engine_failures: number
+    /** Why the engine gave up on it (`learning_skipped`), if it did. */
+    skipped: string | null
+}
+
+/** Where memory stands in a run (#370), from its records. */
+export type MemoryState = {
+    /** Memory is on for this run (`run_started.memory`). */
+    on: boolean
+    /** The project's vault; `null` searches only `default`. */
+    project_vault: string | null
+    /** Each recall point's memories, by its key, once searched. */
+    recalls: Record<string, { point: RecallPoint; memories: RecalledMemory[] }>
+    /** Every memory shown in the run, oldest first; may repeat. */
+    shown: RecalledMemory[]
+    learner: LearnerState
+    /** The learner's memories as saved, and the feedback sent. */
+    saved: { saves: MemorySave[]; feedback: MemoryFeedback[] } | null
+    /** The new memories went on the spec issue (a run with no PR). */
+    reported: boolean
+}
+
+/** A run with memory off, before any memory record. */
+export const EMPTY_MEMORY: MemoryState = {
+    on: false,
+    project_vault: null,
+    recalls: {},
+    shown: [],
+    learner: {
+        result: null,
+        result_seq: null,
+        agent_failure: null,
+        failed_tries: 0,
+        launched_on: null,
+        failed_cheaper: false,
+        engine_failures: 0,
+        skipped: null,
+    },
+    saved: null,
+    reported: false,
+}
+
+/** The agent kinds a learner's turn journals. */
+type LearnerRecord = Extract<
+    JournalRecord,
+    {
+        kind:
+            | 'agent_started'
+            | 'agent_finished'
+            | 'agent_failed'
+            | 'agent_session'
+    }
+>
+
+/** The record if it is one of the learner's agent records, else `null`. */
+export const learnerRecordOf = ({
+    record,
+}: {
+    record: JournalRecord
+}): LearnerRecord | null => {
+    switch (record.kind) {
+        case 'agent_started':
+        case 'agent_finished':
+        case 'agent_failed':
+        case 'agent_session':
+            return record.content.role === 'learner' ? record : null
+        default:
+            return null
+    }
+}
+
+/**
+ * The learner after one of its records: its answer ends any failure; a
+ * failed turn counts a try (or an engine failure in a row), like any
+ * agent's.
+ */
+export const learnerAfter = ({
+    learner,
+    record,
+}: {
+    learner: LearnerState
+    record: LearnerRecord
+}): LearnerState => {
+    switch (record.kind) {
+        case 'agent_started':
+            return { ...learner, launched_on: record.content.model }
+        case 'agent_session':
+            return learner
+        case 'agent_finished':
+            return record.content.role === 'learner'
+                ? {
+                      ...learner,
+                      result: record.content.result,
+                      result_seq: record.seq,
+                      agent_failure: null,
+                      engine_failures: 0,
+                  }
+                : learner
+        case 'agent_failed': {
+            const { role, error, failure, session_id } = record.content
+            const agent_failure = { role, error, failure, session_id }
+            return failure === 'engine'
+                ? {
+                      ...learner,
+                      agent_failure,
+                      engine_failures: learner.engine_failures + 1,
+                  }
+                : {
+                      ...learner,
+                      agent_failure,
+                      engine_failures: 0,
+                      failed_tries: learner.failed_tries + 1,
+                      failed_cheaper:
+                          learner.failed_cheaper ||
+                          ranCheaper(learner.launched_on),
+                  }
+        }
+    }
+}

package/engine/journal/plan-replay.ts

@@ -0,0 +1,139 @@
+/**
+ * The plan as replay rebuilds it: rate limits hit, limit and usage-line
+ * waits, and billing stops, from agents' sessions and the wait records.
+ */
+import type { JournalRecord, UsageLineWindow } from './journal-record'
+
+import type { AgentRole } from '../agents/role-results'
+import { sessionSignal } from '../limits/plan-signals'
+
+/**
+ * Where the run stands with the plan, from agents' rate-limit readings and
+ * the limit-wait and stop records.
+ */
+export type PlanState = {
+    /**
+     * The latest rejected rate limit no limit wait has started for yet: the
+     * window, its reset (seconds since the epoch), the agent that hit it, and
+     * when the session was journaled.
+     */
+    hit: {
+        rate_limit_type: string | null
+        resets_at: number | null
+        ticket: number | null
+        role: AgentRole | null
+        time: string
+    } | null
+    /** The limit wait under way: when it ends, and what it is for. */
+    wait: {
+        until: string
+        resets_at: string | null
+        rate_limit_type: string | null
+    } | null
+    /** Every limit wait's reset so far, oldest first; the spec hears of each new one once. */
+    resets_announced: (string | null)[]
+    /** The first sign of per-token billing in any session, if any. */
+    billing: { reason: string } | null
+    /** Set once a billing stop is journaled. It sticks. */
+    billing_stopped: { reason: string } | null
+    /** The usage-line wait under way: its window, line, reading, and end. */
+    usage_wait: {
+        window: UsageLineWindow
+        line: number
+        percent: number
+        until: string
+    } | null
+    /**
+     * The latest time the run is known to have waited until: the `until` of
+     * a limit wait that ended, or of a usage-line wait that ended at its
+     * reset. A reading whose window resets by then is out of date.
+     */
+    waited_until: string | null
+}
+
+type PlanRecord = Extract<
+    JournalRecord,
+    {
+        kind:
+            | 'agent_session'
+            | 'run_stopped'
+            | 'limit_wait_started'
+            | 'limit_wait_ended'
+            | 'usage_line_wait_started'
+            | 'usage_line_wait_ended'
+    }
+>
+
+/** The later of two ISO times; the first may be missing. */
+const laterOf = (a: string | null, b: string): string =>
+    a !== null && Date.parse(a) >= Date.parse(b) ? a : b
+
+/** The plan state after one record. */
+export const planAfter = ({
+    plan,
+    record,
+}: {
+    plan: PlanState
+    record: PlanRecord
+}): PlanState => {
+    switch (record.kind) {
+        case 'agent_session': {
+            const signal = sessionSignal({ session: record.content.session })
+            if (signal.kind === 'billing') {
+                return {
+                    ...plan,
+                    billing: plan.billing ?? { reason: signal.reason },
+                }
+            }
+            if (signal.kind === 'ok') return plan
+            return {
+                ...plan,
+                hit: {
+                    rate_limit_type: signal.rate_limit_type,
+                    resets_at: signal.resets_at,
+                    ticket: record.ticket,
+                    role: record.content.role,
+                    time: record.time,
+                },
+            }
+        }
+        case 'run_stopped':
+            return record.content.billing
+                ? {
+                      ...plan,
+                      billing: plan.billing ?? {
+                          reason: record.content.reason,
+                      },
+                      billing_stopped: { reason: record.content.reason },
+                  }
+                : plan
+        case 'limit_wait_started': {
+            const { until, resets_at, rate_limit_type } = record.content
+            return {
+                ...plan,
+                hit: null,
+                wait: { until, resets_at, rate_limit_type },
+                resets_announced: [...plan.resets_announced, resets_at],
+            }
+        }
+        case 'limit_wait_ended':
+            return {
+                ...plan,
+                wait: null,
+                waited_until: laterOf(plan.waited_until, record.content.until),
+            }
+        case 'usage_line_wait_started': {
+            const { window, line, percent, until } = record.content
+            return { ...plan, usage_wait: { window, line, percent, until } }
+        }
+        case 'usage_line_wait_ended':
+            return {
+                ...plan,
+                usage_wait: null,
+                waited_until:
+                    record.content.reason === 'reset'
+                        ? laterOf(plan.waited_until, record.content.until)
+                        : plan.waited_until,
+            }
+    }
+}

package/engine/journal/pull-request-entries.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+/** The journal entries of the run's pull request: its changeset, and the PR. */
+
+/** A changeset's bump: from the spec's `release:*` label, patch with none. */
+export const ChangesetBumpSchema = z.enum(['patch', 'minor', 'major', 'none'])
+
+export type ChangesetBump = z.infer<typeof ChangesetBumpSchema>
+
+/**
+ * The engine committed the run's one changeset (#461) at `path` on the run
+ * branch and pushed it (`sha` is the run branch's HEAD after). `packages`
+ * are the ones it names. `path` is `null` when nothing was written: the
+ * spec is `release:none` (#476), or the repo no longer had a changesets
+ * config.
+ */
+export const ChangesetWrittenEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('changeset_written'),
+    content: z.object({
+        path: z.string().nullable(),
+        bump: ChangesetBumpSchema,
+        packages: z.array(z.string()),
+        sha: z.string(),
+    }),
+})
+
+export const PullRequestOpenedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('pull_request_opened'),
+    content: z.object({
+        number: z.number().int().positive(),
+        url: z.string(),
+        head: z.string(),
+        base: z.string(),
+        title: z.string(),
+        body: z.string(),
+    }),
+})