wingfoil 0.2.2 → 0.3.0

package/dist/agent/run-log.d.ts

@@ -0,0 +1,254 @@
+import { type CoreResult } from '../core/types';
+/** The literal of a value the agent did not report (§2.6): never `0`, `null` or an absent key. */
+export declare const NOT_REPORTED: "not-reported";
+/** `workflow` of a run with no step (§4.2 key 3). */
+export declare const NO_WORKFLOW: "n/a";
+/** `phase`, and the id's phase segment, of a run with no step (§4.3; reserved by `spec-003`). */
+export declare const ADHOC_PHASE: "adhoc";
+/** The record's keys, in the order §4.2 fixes and every line carries. */
+export declare const RUN_RECORD_KEYS: readonly ["id", "element", "workflow", "phase", "role", "mode", "agent", "adapter", "agent_version", "model", "session", "tokens", "wingfoil", "state_ref", "duration_ms", "exit_status", "result", "notes"];
+/** The keys of the record's `tokens` object, in order (§4.2 key 12). */
+export declare const RUN_TOKEN_KEYS: readonly ["input", "output", "cache_read", "cache_write"];
+/** A count the agent reported, or {@link NOT_REPORTED}. */
+export type ReportedCount = number | typeof NOT_REPORTED;
+/** The record's `tokens` (§4.2 key 12, `dl-114` Q2 (b)). */
+export interface RunTokens {
+    readonly input: ReportedCount;
+    readonly output: ReportedCount;
+    readonly cache_read: ReportedCount;
+    readonly cache_write: ReportedCount;
+}
+/** One run record (`spec-016` §4.2). Field names are the JSON keys. */
+export interface RunRecord {
+    /** Run id, `<element-id>/<phase>/<n>` (§4.3). */
+    readonly id: string;
+    /** `<type>:<id>` (`spec-008` §7). */
+    readonly element: string;
+    /** Workflow name, or {@link NO_WORKFLOW}. */
+    readonly workflow: string;
+    /** Phase name, or {@link ADHOC_PHASE}. */
+    readonly phase: string;
+    readonly role: string;
+    /** The mode that ran: `fresh` in v0.3. */
+    readonly mode: string;
+    /** `team.agents[].name`. */
+    readonly agent: string;
+    /** `<built-in|custom>/<name>`. */
+    readonly adapter: string;
+    readonly agent_version: string;
+    readonly model: string;
+    readonly session: string;
+    readonly tokens: RunTokens;
+    /** The launching build, `"<semver> (<sha>)"` (`dl-111`). */
+    readonly wingfoil: string;
+    /** Full sha the context was assembled at. */
+    readonly state_ref: string;
+    /** Wall-clock, spawn to exit. A record of what happened; it never enters a context. */
+    readonly duration_ms: number;
+    /** The agent's exit code, or `signal:<NAME>`. */
+    readonly exit_status: number | string;
+    /** `n/a` for an interactive launch; `PASS`/`FAIL`/`ERROR` for a headless one. */
+    readonly result: string;
+    /** `<element-id>#execution-notes`, or `none` (§4.2 key 18). */
+    readonly notes: string;
+}
+/**
+ * Whether `id` is a run id of the element `elementId` (§4.3): the element id, a `/`, a phase segment
+ * in `spec-003`'s phase-name class (a lowercase letter, then lowercase letters, digits and `-`), a
+ * `/`, and a decimal count from 1 with no padding; `elementId` itself in `spec-009`'s ID class.
+ */
+export declare function isRunId(id: string, elementId: string): boolean;
+/**
+ * The element id of the run id `value` (§4.3), or `null` when `value` is not a run id of any element
+ * — the parse a caller that only has the id needs (`agent show <run-id>`, task-220). An element id is
+ * in `spec-009`'s ID class, which holds no `/`, so a run id has exactly three `/`-separated segments
+ * and the first one is the element's.
+ */
+export declare function runIdElementId(value: string): string | null;
+/**
+ * The run id `<element-id>/<phase>/<n>` (§4.3).
+ *
+ * @throws Error when the result would not be a run id ({@link isRunId}): a caller passing a malformed
+ *   element id, phase or count has a defect, not a refusal to report.
+ */
+export declare function formatRunId(elementId: string, phase: string, n: number): string;
+/**
+ * The record as its log line (§4.2): one JSON object, keys in {@link RUN_RECORD_KEYS} order whatever
+ * order `record` was built in, no insignificant whitespace, `\n`-terminated.
+ *
+ * The record is validated first, with the reader's rules except key order, so the writer can never
+ * produce a line the reader refuses: an absent key, a `null`, a fractional count is refused rather than
+ * written.
+ *
+ * @throws Error `run record is not valid: <detail>` — a caller defect.
+ */
+export declare function serializeRunRecord(record: RunRecord): string;
+/**
+ * Read a run log strictly (§4.5): every line JSON, exactly the §4.2 keys in order with valid types, an
+ * `id` whose element segment is the file's basename (`<runs>/<element-id>.jsonl`), no id twice, and each
+ * line byte for byte the writer's serialization of its record — no CR, no whitespace outside a string
+ * (bug-288).
+ * The last line must be `\n`-terminated, since an append to an unterminated line would corrupt both.
+ *
+ * @param text - The file's content.
+ * @param path - Root-relative path of the file; its basename without `.jsonl` is the element id, and it
+ *   is named in every refusal.
+ * @returns The records in line order, or `VALIDATION` with the §4.5 message for the first violation.
+ */
+export declare function parseRunLog(text: string, path: string): CoreResult<RunRecord[]>;
+/**
+ * The run log `path` as commit `rev` holds it, read strictly ({@link parseRunLog}); a log the commit
+ * does not hold is no records.
+ *
+ * @returns `VALIDATION`/`NOT_FOUND` from a `rev` that is malformed or names no commit.
+ */
+export declare function readRunLogAt(root: string, rev: string, path: string): CoreResult<RunRecord[]>;
+/**
+ * The run-log directory `dir` (`dna.yaml` `paths.runs`' one entry) as a root-relative POSIX path, joined
+ * as {@link resolveRunLogPath} joins it (a trailing slash, `./` or a doubled `/` changes nothing): `''` for
+ * the root itself.
+ */
+export declare function runLogDirPrefix(root: string, dir: string): string;
+/**
+ * Whether the root-relative `path` is a run log of the directory `prefix` ({@link runLogDirPrefix}): a
+ * `.jsonl` file directly inside it (§4.1, `<runs>/<element-id>.jsonl`). Anything else there — a README, a
+ * file in a subdirectory — is not a run log: no reader reads it, and nothing reports it (task-240 review F5).
+ */
+export declare function isRunLogPath(prefix: string, path: string): boolean;
+/**
+ * Every run log commit `sha` holds in the run-log directory `dir` (§4.1, §4.5): each `<element-id>.jsonl`
+ * directly inside it ({@link isRunLogPath}), ordered by element id in byte order — the basename without
+ * `.jsonl`, never the whole path, under which `minor-v0.3.1.jsonl` would sort before `minor-v0.3.jsonl`
+ * (task-240 review F1) — each read strictly ({@link parseRunLog}), its records in line order. The reader
+ * `agent list` lists past runs from (task-240, `spec-016` §5).
+ *
+ * `dir` is confined to the project root first (`REQ-SEC-06`), unless it is the root itself, the boundary.
+ *
+ * @param dir - `dna.yaml` `paths.runs`' one directory, non-blank.
+ * @returns The records, or the first §4.5 violation (`VALIDATION`), or a confinement refusal.
+ * @throws `StorageError` when git cannot list the commit.
+ */
+export declare function readRunLogsAt(root: string, sha: string, dir: string): CoreResult<RunRecord[]>;
+/**
+ * The run-log file of `elementId` (§4.1): `<runs>/<element-id>.jsonl`, joined as a path (a trailing
+ * slash, `./` or a doubled `/` in `paths.runs` changes nothing) and confined to the project root
+ * (`REQ-SEC-06`): `paths.runs` accepts an absolute or a `../` value, so the file it names is checked
+ * where it is resolved.
+ *
+ * @param runs - `dna.yaml` `paths.runs` (one directory; absent when undeclared).
+ * @param action - The verb of the confinement refusal (`cannot <action> '<path>'`): `write` for the
+ *   recorder, `read` for a reader that opens the working tree's file (`agent show`'s hint, task-220).
+ * @returns The root-relative POSIX path, or `VALIDATION`: `dna.yaml declares no run log (paths.runs)`
+ *   (`NO_RUN_LOG`, §3.7) for an absent or blank value; a confinement refusal; an element id outside
+ *   `spec-009`'s ID class.
+ */
+export declare function resolveRunLogPath(root: string, runs: readonly string[] | undefined, elementId: string, action?: 'write' | 'read'): CoreResult<string>;
+/**
+ * Whether the run log `logPath` may be appended to and committed now: confined to the project root
+ * with no symlinked leaf (`requireConfinedWriteTarget`), inspectable by git — no directory on the way
+ * to it is a symbolic link, which would make an empty `git status` mean nothing
+ * (`requireInspectableTarget`, task-131) — and unmodified against `HEAD` in the index and the working
+ * tree, an untracked file included (`CONFLICT` `run log <path> has uncommitted changes`, §3.7).
+ * {@link recordRun} asks it again at step 17.
+ */
+export declare function requireWritableRunLog(root: string, logPath: string): CoreResult<undefined>;
+/**
+ * The run-log pre-flight of `agent execute`'s pipeline step 6 (`spec-016` §3.3), for a caller to run
+ * **before the spawn**, so a run whose record could not be committed is refused before it starts:
+ * the log is declared (`NO_RUN_LOG`), confined, inspectable and unmodified ({@link resolveRunLogPath},
+ * then {@link requireWritableRunLog}).
+ *
+ * @param runs - `dna.yaml` `paths.runs`, read at `HEAD`.
+ * @returns The root-relative run-log path the record will be committed to.
+ */
+export declare function runLogPreflight(root: string, runs: readonly string[] | undefined, elementId: string): CoreResult<string>;
+/** What {@link nextRunId} counts. */
+export interface NextRunIdInput {
+    /** Root-relative run-log path ({@link resolveRunLogPath}). */
+    readonly logPath: string;
+    /** `<type>:<id>`. */
+    readonly element: string;
+    /** Phase name, or {@link ADHOC_PHASE}. */
+    readonly phase: string;
+    /** The commit the context is assembled at. */
+    readonly stateRef: string;
+}
+/**
+ * The next run id (§4.3): `<element-id>/<phase>/<n>`, `n` = 1 + the records in the log **at
+ * `state_ref`** whose `element` and `phase` match, whatever their workflow. Later commits and the
+ * working tree do not count, so two clones of the same history derive the same id.
+ *
+ * @returns The id, or the strict reader's `VALIDATION` for a log at `state_ref` it refuses.
+ */
+export declare function nextRunId(root: string, input: NextRunIdInput): CoreResult<string>;
+/**
+ * The body of the `## Execution Notes` section of a Markdown document, or `null` when it has none.
+ *
+ * The section is found by its **heading line** — a line that is exactly `## Execution Notes` — never
+ * by substring, so an inline `` `## Execution Notes` `` in prose, a YAML frontmatter value or
+ * `## Triage & Execution Notes` is not it. It runs to the next level-1 or level-2 heading, or the end;
+ * lines inside a fenced code block are not headings. CRLF reads as LF.
+ */
+export declare function executionNotesSection(markdown: string): string | null;
+/** The three texts {@link notesField} compares; `null` for one that does not exist. */
+export interface NotesFieldInput {
+    /** The element type's template (`template.file`), read at `HEAD`. */
+    readonly template: string | null;
+    /** The element at `state_ref`. */
+    readonly atStateRef: string | null;
+    /** The element at `HEAD` after the run. */
+    readonly atHead: string | null;
+}
+/**
+ * The record's `notes` (§4.2 key 18, `dl-135` Q2 (c)): `<element-id>#execution-notes` when the
+ * element's `## Execution Notes` section differs between `state_ref` and `HEAD`, else `none`. Always
+ * `none` for a type whose template has no such section.
+ */
+export declare function notesField(elementId: string, input: NotesFieldInput): string;
+/** Where {@link deriveNotesField} reads. */
+export interface DeriveNotesFieldInput {
+    readonly elementId: string;
+    /** Root-relative path of the element's document. */
+    readonly elementPath: string;
+    /** Root-relative path of the type's `template.file`. */
+    readonly templatePath: string;
+    readonly stateRef: string;
+}
+/**
+ * {@link notesField} over git: the template and the element at `HEAD`, the element at `state_ref`.
+ * Committed states only, so notes left uncommitted yield `none`.
+ */
+export declare function deriveNotesField(root: string, input: DeriveNotesFieldInput): string;
+/** The subject of the commit that records the run `runId` (§4.4): `agent: record <run-id>`, outside `wf()`. */
+export declare function recordSubject(runId: string): string;
+/** What a recorded run returns: the record and the commit that holds it. */
+export interface RecordedRun {
+    readonly record: RunRecord;
+    readonly sha: string;
+}
+/**
+ * Append `record` to its run log and commit it (§4.4, §4.3 collision, §3.7).
+ *
+ * The commit contains only `logPath` (`commitPaths`, `--only`): the agent's uncommitted and staged
+ * edits elsewhere stay as they are. Its subject is `agent: record <run-id>`, outside the `wf()`
+ * grammar because the run log is not Memory, and `commitPaths` adds `dl-111`'s `WingFoil-Version:`
+ * trailer; there is no other body.
+ *
+ * Refusals, in order, none of which writes anything:
+ * - `VALIDATION` — `record` is not a valid record, including an id that is not the one its own
+ *   `element` and `phase` produce (no `details`: there is no line to give back);
+ * - every later refusal carries the record as a `details` line, so the run is not lost (§3.7, §4.3):
+ *   `VALIDATION` for a record not of this log's element (its id's element segment is not the file's
+ *   basename), a log path that leaves the project root, is a symlink, or lies beyond a symlinked
+ *   directory; `CONFLICT` `run log <path> has uncommitted changes` ({@link requireWritableRunLog});
+ *   the strict reader's `VALIDATION` for the log at `HEAD`; `CONFLICT` `run id <run-id> already
+ *   recorded at HEAD`.
+ *
+ * The append and the commit go through `writeAndCommit` (task-210): under a dry run the commit is
+ * planned and nothing is written. A commit git refuses (a hook, a held `index.lock`, …) is `IO` `run
+ * <run-id> not recorded: <cause>` with the record as a `details` line, the cause naming no absolute
+ * path; the file, any directory the append created, and the index entry are put back as they were. A
+ * write the filesystem refuses (`EACCES`, `ENOSPC`) is the same `IO` refusal, the record kept.
+ */
+export declare function recordRun(root: string, logPath: string, record: RunRecord): CoreResult<RecordedRun>;
+//# sourceMappingURL=run-log.d.ts.map

package/dist/agent/run-log.d.ts.map

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