@wjarka/cezarion 0.16.0 → 0.17.0

package/dist/contract/query-requests.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * Query schemas for the READ routes — deliberately permissive.
+ *
+ * These exist to make a query key VISIBLE to the route type (`hc` refuses a `query` argument for
+ * a key no validator declares), NOT to narrow what the route accepts. Every one of these handlers
+ * compares `=== '1'` and treats everything else as false, so `?refresh=0` is a successful request
+ * today; a literal schema would silently turn it into a 400. The comparison stays in the handler
+ * and the validator stays out of its way.
+ *
+ * The one route that really is strict on the wire — `GET /github/prs/:number/changes`, which 400s
+ * on `?refresh=true` — keeps its own `z.enum(['1'])` schema next to the route.
+ */
+/**
+ * One query value, matching what `c.req.query('k')` did before these routes were validated.
+ *
+ * Hono's query validator hands a REPEATED key as an array (`?wait=1&wait=1` → `['1','1']`), where
+ * `c.req.query()` silently took the first. A plain `z.string()` therefore turns a request that
+ * used to answer 200 into a 400 — a wire change no caller asked for. Collapsing to the first
+ * value keeps the old behaviour, and the client still sees a plain `key?: string`.
+ */
+export declare const queryValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+export declare const refreshQuery: z.ZodObject<{
+    refresh: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const waitQuery: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const modelDiscoveryQuerySchema: z.ZodObject<{
+    runner: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>, z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>>;
+}, z.core.$strip>;
+export declare const strictRefreshQuerySchema: z.ZodObject<{
+    refresh: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>> & z.ZodType<"1" | undefined, string | string[] | undefined, z.core.$ZodTypeInternals<"1" | undefined, string | string[] | undefined>>;
+}, z.core.$strip>;
+export declare const browseQuerySchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+    showHidden: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const worktreeFilesQuerySchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+    raw: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const commitQuerySchema: z.ZodObject<{
+    structured: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;

package/dist/contract/repo-requests.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const gitCommitSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const reclaimBodySchema: z.ZodObject<{}, z.core.$loose>;
+export declare const repoBranchSchema: z.ZodObject<{
+    name: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const reclaimRunParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strip>;

package/dist/contract/run-labels.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The label a run is listed under.
+ *
+ * No runtime import, so a consumer of it loads no schema (hearsay-tools/cezarion#1237).
+ */
+import type { RunRecord } from './runs.ts';
+/** `(planned)` and `(inbox)` chains carry their meaning in their first agent step's name. */
+export declare function runWorkflowLabel(run: Pick<RunRecord, 'workflow' | 'steps'>): string;

package/dist/contract/run-limits.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Page bounds the run-summary routes share with their callers.
+ *
+ * No runtime import, so a consumer of these loads no schema (hearsay-tools/cezarion#1237).
+ */
+/** The archived roots `GET /run-summaries/archived` answers per page by default, and at most (#864). */
+export declare const ARCHIVED_RUNS_PAGE_DEFAULT = 50;
+export declare const ARCHIVED_RUNS_PAGE_MAX = 200;

package/dist/contract/run-predicates.d.ts

@@ -0,0 +1,32 @@
+import { type ArchiveFinishedScope, type RunRecord } from './runs.ts';
+/**
+ * Facts about a run that the store, the server, the engine and the cockpit all decide on, each
+ * defined once here so that no reader restates one in its own code (hearsay-tools/cezarion#1496).
+ * Each takes the record, never a bare status, so no caller can miss a usage-limit hold
+ * (hearsay-tools/cezarion#1434). `isUsageLimitHold` lives beside `computeWaitingOn` in `waits.ts`.
+ */
+type OwnershipInput = Pick<RunRecord, 'status'> & Partial<Pick<RunRecord, 'autoResumeAt'>>;
+/**
+ * The engine still owns the run: queued (parked but claimed), running or waiting. A usage-limit
+ * hold is `waiting` with no session (hearsay-tools/cezarion#1236): the engine has let go of it
+ * until its resume, so it keeps a closed run's controls. `review` is not owned: a parked review
+ * can be continued, archived or deleted like any finished run.
+ */
+export declare function engineOwnsRun(run: OwnershipInput): boolean;
+/** A live agent session owns the run: the engine owns it and it has left the line. */
+export declare function isSessionOpen(run: OwnershipInput): boolean;
+/** What the archive sweep reads. The store passes records and summaries, the cockpit summaries. */
+export type SweepInput = Pick<RunRecord, 'archived' | 'status'> & Partial<Pick<RunRecord, 'pinned'>> & {
+    delegation?: {
+        role?: string;
+    } | null | undefined;
+    automationId?: string | undefined;
+};
+/**
+ * The bulk-archive sweep's one predicate (hearsay-tools/cezarion#780, `POST /runs/archive-finished`): finished (a
+ * usage-limit hold is `waiting`, hearsay-tools/cezarion#1236), not archived, not an owned worker
+ * (those leave with their parent), in the tab `automation` names when given, then filtered by pin
+ * state (`scope` absent = both).
+ */
+export declare function isSweepable(run: SweepInput, scope?: ArchiveFinishedScope, automation?: boolean): boolean;
+export {};

package/dist/contract/run-requests.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export declare const queuedMessagePatchSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mediaType: z.ZodString;
+        data: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const continueSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mediaType: z.ZodString;
+        data: z.ZodString;
+    }, z.core.$strip>>>;
+    runner: z.ZodOptional<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodString>;
+    agentProfile: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const archiveSchema: z.ZodObject<{
+    archived: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const openInSchema: z.ZodObject<{
+    target: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/contract/run-search.d.ts

@@ -0,0 +1,193 @@
+import type { RunSummary } from './runs.ts';
+/**
+ * The one rule for "does this run match what was typed" (hearsay-tools/cezarion#1807). The project
+ * list, All tasks, the archived pages, the ⌘K palette and the SQL prefilter under the last two all
+ * ask it, so a run found in one place is found in the others unless a reader says why not, in an
+ * option of the call. A new searchable field is one entry in `RUN_SEARCH_FIELDS`.
+ *
+ * Every whitespace-separated token must match. A token matches a substring of a text field. A
+ * number, with a leading `#` stripped, also matches a reference number EXACTLY and an id as a
+ * prefix, never digits inside a URL: `86` finding #864 would turn every short query into noise.
+ * Any other token also matches inside the id and the URLs.
+ *
+ * `import type` only, on purpose: the cold reader imports this module and must stay cheap to load.
+ */
+/** The fields of a run the search reads. A list row, an index row and a full record all fit. */
+export type RunSearchRun = Pick<RunSummary, 'id' | 'title' | 'titleSummary' | 'branch' | 'workflow' | 'workflowLabel' | 'automationId' | 'pullRequestUrl' | 'referencedPullRequestUrl' | 'referencedIssueUrl' | 'pullRequests' | 'prNumber' | 'issueNumber' | 'markerRefs'>;
+/**
+ * Which fields a reader looks in. `stored` is everything the run holds: the server's search, which
+ * reaches history and so also matches ids, URLs and every reference number. `shown` is only what a
+ * row prints, plus the reference numbers the row shows: the cockpit's lists, which must not show a
+ * row for a reason the reader cannot see. The one exception is the branch, which a folded column
+ * hides: pasting a branch name from a terminal to find its task is a deliberate gesture.
+ */
+export type RunSearchScope = 'stored' | 'shown';
+/** `tokens`: every token must match, in any field. `phrase`: the trimmed query is one token. */
+export type RunSearchMode = 'tokens' | 'phrase';
+/**
+ * Automation display names by automation id, for a search whose list shows each task's origin line
+ * (hearsay-tools/cezarion#1616). With a lookup, a task an automation launched also matches by that
+ * automation's name, or by its recorded id when no definition names it, as the cockpit's own
+ * filter does. Without one, the automation is not searched: the ⌘K palette shows no origin line,
+ * and a match with no visible reason is noise.
+ */
+export type AutomationNames = ReadonlyMap<string, string>;
+/** What a `shown` reader knows that the run does not carry. A field it leaves out is not searched. */
+export interface RunSearchExtras {
+    /** The title the row prints. */
+    displayTitle?: string | undefined;
+    /** The origin line's automation: its name, or its recorded id. */
+    automation?: string | undefined;
+    projectName?: string | undefined;
+    tags?: readonly string[] | undefined;
+    /** The reference numbers the row shows. Called only when a token is a number. */
+    references?: (() => readonly number[]) | undefined;
+}
+interface SearchOptionsBase {
+    mode?: RunSearchMode;
+}
+/** The server's reach. Without `automationNames` the automation is not searched. */
+export interface StoredRunSearch extends SearchOptionsBase {
+    scope?: 'stored';
+    automationNames?: AutomationNames | undefined;
+}
+/** A list's reach: what it prints, from `extras`. */
+export interface ShownRunSearch extends SearchOptionsBase {
+    scope: 'shown';
+    extras: RunSearchExtras;
+    /** Fields this reader's rows do not print. A field added later is searched unless listed here. */
+    omit?: readonly RunSearchFieldId[];
+}
+export type RunSearchOptions = StoredRunSearch | ShownRunSearch;
+type Texts = (run: RunSearchRun, extras: RunSearchExtras) => ReadonlyArray<string | undefined>;
+interface FieldCommon {
+    readonly id: string;
+    readonly scopes: readonly RunSearchScope[];
+    /**
+     * `summary`: the text sits verbatim in the run's stored summary JSON, which is all the SQL
+     * prefilter can read. `reader`: the reader hands it in (`universe` lists every text it could be).
+     */
+    readonly source: 'summary' | 'reader';
+    /** Every text a `reader` field could hold under `options`, so the prefilter leaves out a token
+     *  that could match through it. Required for a `reader` field in the stored scope. */
+    readonly universe?: (options: StoredRunSearch) => readonly string[];
+}
+/** How a token matches: `text` by substring; `identifier` by prefix when it is a number and by
+ *  substring otherwise; `link` by substring unless it is a number; `reference` by number alone. */
+export type RunSearchField = FieldCommon & ({
+    readonly kind: 'text' | 'identifier' | 'link';
+    readonly texts: Texts;
+} | {
+    readonly kind: 'reference';
+    readonly numbers: (run: RunSearchRun, extras: RunSearchExtras) => readonly number[];
+});
+/** The `#N` in a forge URL — `…/pull/774` → 774. Null when the tail is not a number, so a URL
+ *  shape we do not recognise invalidates nothing rather than inventing a key. */
+export declare function refNumberFromUrl(url: string): number | null;
+declare function heldReferences(run: RunSearchRun): number[];
+/**
+ * THE list of searchable fields. Add a field here and every reader searches it. A reader that
+ * must not says so in `omit`, in its own call. The summary-sourced entries are what `runs.db`
+ * stores, which is the only thing the SQL prefilter sees (`sqlPrefilterTokens`).
+ */
+export declare const RUN_SEARCH_FIELDS: readonly [{
+    readonly id: 'title';
+    readonly kind: 'text';
+    readonly scopes: readonly ["stored"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => string[];
+}, {
+    readonly id: 'titleSummary';
+    readonly kind: 'text';
+    readonly scopes: readonly ["stored"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => (string | undefined)[];
+}, {
+    readonly id: 'displayTitle';
+    readonly kind: 'text';
+    readonly scopes: readonly ["shown"];
+    readonly source: 'reader';
+    readonly texts: (_run: RunSearchRun, extras: RunSearchExtras) => (string | undefined)[];
+}, {
+    readonly id: 'branch';
+    readonly kind: 'text';
+    readonly scopes: readonly ["stored", "shown"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => (string | undefined)[];
+}, {
+    readonly id: 'workflow';
+    readonly kind: 'text';
+    readonly scopes: readonly ["stored", "shown"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => string[];
+}, {
+    readonly id: 'workflowLabel';
+    readonly kind: 'text';
+    readonly scopes: readonly ["stored", "shown"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => string[];
+}, {
+    readonly id: 'automation';
+    readonly kind: 'text';
+    readonly scopes: readonly ["stored", "shown"];
+    readonly source: 'reader';
+    readonly texts: (_run: RunSearchRun, extras: RunSearchExtras) => (string | undefined)[];
+    readonly universe: (options: StoredRunSearch) => string[];
+}, {
+    readonly id: 'projectName';
+    readonly kind: 'text';
+    readonly scopes: readonly ["shown"];
+    readonly source: 'reader';
+    readonly texts: (_run: RunSearchRun, extras: RunSearchExtras) => (string | undefined)[];
+}, {
+    readonly id: 'tags';
+    readonly kind: 'text';
+    readonly scopes: readonly ["shown"];
+    readonly source: 'reader';
+    readonly texts: (_run: RunSearchRun, extras: RunSearchExtras) => readonly string[];
+}, {
+    readonly id: 'id';
+    readonly kind: 'identifier';
+    readonly scopes: readonly ["stored"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => string[];
+}, {
+    readonly id: 'urls';
+    readonly kind: 'link';
+    readonly scopes: readonly ["stored"];
+    readonly source: 'summary';
+    readonly texts: (run: RunSearchRun) => (string | undefined)[];
+}, {
+    readonly id: 'heldReferences';
+    readonly kind: 'reference';
+    readonly scopes: readonly ["stored"];
+    readonly source: 'summary';
+    readonly numbers: typeof heldReferences;
+}, {
+    readonly id: 'shownReferences';
+    readonly kind: 'reference';
+    readonly scopes: readonly ["shown"];
+    readonly source: 'reader';
+    readonly numbers: (_run: RunSearchRun, extras: RunSearchExtras) => readonly number[];
+}];
+export type RunSearchFieldId = (typeof RUN_SEARCH_FIELDS)[number]['id'];
+/** The query as lowercased, whitespace-split tokens, empties dropped. */
+export declare function searchTokens(query: string): string[];
+/**
+ * Whether every token of `query` matches `run`, under `options` (stored scope, every-token mode
+ * and no automation names when omitted). A blank query matches nothing: a list that shows every
+ * row for a blank query decides that itself.
+ */
+export declare function matchesRunSearch(run: RunSearchRun, query: string, options?: RunSearchOptions): boolean;
+/**
+ * The tokens SQL may narrow rows with, as `instr(lower(summary), ?) > 0` over the stored summary
+ * JSON. Only tokens that read the same there: ASCII, since SQLite's `lower()` folds ASCII alone,
+ * and without `"` or `\`, which JSON escapes. Leaving a token out only widens the prefilter;
+ * `matchesRunSearch` still checks it.
+ *
+ * A token inside a text a `reader` field could hold is left out too (today, an automation's name):
+ * the summary holds the automation's id, not its name, so the row it should find would never
+ * reach `matchesRunSearch`. Pass the same options to both.
+ */
+export declare function sqlPrefilterTokens(query: string, options?: StoredRunSearch): string[];
+export {};