@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-jobs.types.d.ts

@@ -0,0 +1,412 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ITimestamp } from '@aglyn/shared-util-timestamp';
+import type { AiEffort } from '../providers/contract';
+import type { AiLoadEstimate } from '../runtime/ai-palette';
+import type { AiBuildPlan } from './ai-build-plan';
+/**
+ * AI generation jobs (AGL-2904).
+ *
+ * A job is one customer brief carried through one or more model steps by a
+ * Firestore state machine, so that work longer than a request can survive
+ * the request: the console route runs what it can inline, and the platform
+ * job beat resumes whatever is left. The document is the whole state — no
+ * process holds anything the next beat cannot read back.
+ *
+ * ── Outputs are drafts, never a publish ──────────────────────────────────
+ *
+ * Every output a job produces is a NEW draft or a new unpublished version of
+ * an existing resource. A job never flips a version pointer, never registers
+ * a route and never sends anything; a person opens the draft the job names
+ * and publishes it through the door that already exists for that resource.
+ * That is what lets a job run with no visitor, no session and no confirm
+ * gate — the thing it writes cannot be seen by anyone but the workspace
+ * until a member chooses otherwise.
+ *
+ * ── The lease ────────────────────────────────────────────────────────────
+ *
+ * A step runs under a lease: an owner id and an `until` instant. Two beats
+ * fire a minute apart against a 120 s function timeout, and a console route
+ * may still be running the first step when the first beat looks, so the
+ * lease is what stops the same step being run — and metered — twice. A
+ * claim is a transaction that refuses while another owner's lease is live;
+ * an expired lease is simply claimable, which is also how a step abandoned
+ * by a frozen process is recovered.
+ */
+/**
+ * What a job produces. `text` and `theme` have runners; every other kind is
+ * registered and refuses with "not available yet" until its own issue lands,
+ * so a kind's presence in the union says the job model accepts it, not that
+ * a runner exists.
+ */
+export type AiJobKind = 'page' | 'component' | 'layout' | 'template' | 'edit' | 'seo' | 'site' | 'email' | 'campaign' | 'form' | 'experiment' | 'insight' | 'products' | 'crm' | 'onboarding' | 'workflow' | 'text' | 'theme';
+/** The union as a value, so a route can validate a body against it. */
+export declare const AI_JOB_KINDS: readonly AiJobKind[];
+/**
+ * `queued` — waiting for a runner; `running` — a step holds the lease;
+ * `needs_input` — the job stopped for something only the workspace can
+ * change (credits, a cap, a switch), and the beat tries it again once that
+ * may have changed; `needs_review` — the job stopped for a person's decision
+ * (AGL-2935): its plan is ready to confirm, or an answer broke a building
+ * rule on its re-ask. No timer can make that decision, so neither the beat
+ * nor anything but that person resumes it. The last three are terminal.
+ */
+export type AiJobStatus = 'queued' | 'running' | 'needs_input' | 'needs_review' | 'done' | 'failed' | 'canceled';
+export declare const AI_JOB_TERMINAL_STATUSES: readonly AiJobStatus[];
+export type AiJobStepStatus = 'pending' | 'running' | 'done' | 'failed';
+export interface AiJobStep {
+    /** Stable within the job (`plan`, `draft`, `generate`), unique per job. */
+    name: string;
+    status: AiJobStepStatus;
+    startedAt?: ITimestamp | null;
+    endedAt?: ITimestamp | null;
+    /** Credits this step has actually cost, at the plan's credit rate. */
+    creditsSpent: number;
+    /** Customer-safe only; provider detail goes to the server log. */
+    error?: string | null;
+    /**
+     * How many times a runner has been handed this step. A retryable provider
+     * failure hands the step back as `pending`; the count is what stops a
+     * provider outage re-running a step forever.
+     */
+    attempts?: number;
+    /**
+     * Passes of a step that works through a list (AGL-2910): each one a
+     * recorded, metered exchange that asked to continue. Attempts count again
+     * from zero after a pass; this count is what bounds the step.
+     */
+    passes?: number;
+    /**
+     * What the step's model calls cost in tokens and time (AGL-2937), summed
+     * over every run that reached the provider. Absent on a step none has.
+     */
+    tokens?: AiJobStepTokens;
+    /**
+     * The ids the step writes its drafts under, by draft (AGL-3079): minted
+     * when the job is created, so every run of the step names the same drafts.
+     * Absent on a step that writes none; a step that records none names its
+     * drafts by the job's own id.
+     */
+    draftIds?: Partial<Record<AiJobDraftSlot, string>>;
+}
+/**
+ * A draft a job's kind always writes (AGL-3079): a screen, layout, template,
+ * form or component; an email design; a campaign; an automation.
+ */
+export type AiJobDraftSlot = 'screen' | 'layout' | 'template' | 'form' | 'component' | 'email' | 'campaign' | 'workflow';
+/**
+ * A step's measure (AGL-2937): the four token counts the meter prices, the
+ * time spent in the runner, and the model and thinking effort of the last
+ * run. The machine writes it beside `creditsSpent`, so what a kind of step
+ * costs in tokens is read off the job rather than inferred from the month.
+ */
+export interface AiJobStepTokens {
+    /** Prompt tokens sent uncached. */
+    input: number;
+    /** Prompt tokens read from the prompt cache. */
+    cachedRead: number;
+    /** Prompt tokens written to the prompt cache. */
+    cacheWrite: number;
+    /** Tokens generated, thinking included. */
+    output: number;
+    /** The model the last run was served by. */
+    model: string | null;
+    /** The thinking effort the last run asked for; `null` when it named none. */
+    effort: AiEffort | null;
+    /** Milliseconds spent in the runner, summed over runs. */
+    latencyMs: number;
+    /** Runs that reached the provider. */
+    runs: number;
+    /**
+     * Why the step's latest runs stopped (AGL-3042), oldest first and the last
+     * run last: each run's stop reason and the tokens it generated, so a pass
+     * cut off at its ceiling reads off the job rather than out of the sums. At
+     * most `AI_JOB_STEP_LAST_RUNS` are kept; absent on a step measured before.
+     */
+    lastRuns?: AiJobStepRunStop[];
+}
+/** One run of a step, by why it stopped (AGL-3042). */
+export interface AiJobStepRunStop {
+    /**
+     * The stop reason of the run's last model call — `tool_use` or `end_turn`
+     * for an answer, `max_tokens` for one cut off at its ceiling, `refusal` —
+     * and `null` when the provider named none.
+     */
+    stopReason: string | null;
+    /** Tokens the run generated, over every model call it made. */
+    output: number;
+}
+export type AiJobOutputResource = 'screen' | 'reusableComponent' | 'layout' | 'template' | 'form' | 'emailScreen' | 'campaign' | 'product' | 'experiment' | 'workflow' | 'text' | 'theme' | 'seo' | 'insight' | 'crm';
+/**
+ * One thing a job wrote. Addressed by resource and id so the console can
+ * build the "open draft" link without knowing what the runner did; `text`
+ * has no document of its own, so its body rides on the output itself.
+ *
+ * A `theme` output is a proposal rather than a document (AGL-2938). A site's
+ * theme is fields on its host document, and writing those fields is the save
+ * the Theme section's editor performs, which a job never does. So the change
+ * set rides on the output as `proposal`, and a person puts it in the editor
+ * and saves it there, or does not.
+ *
+ * An `seo` output is a proposal rather than a document (AGL-2910): search
+ * listing values for a page or a product, or a site audit's findings and
+ * fixes. A screen's listing is served from the screen document itself, so a
+ * job never writes it; the values ride on the output as `proposal`, a person
+ * puts them in the editor and saves them there, and an audit's content fixes
+ * become new versions only when a person applies them.
+ *
+ * A `crm` output is a proposal too (AGL-2917): a record's summary and next
+ * step, an email draft, or an import's column matches. The CRM's own task
+ * form, stage route, composer and import drawer are the writes, and a person
+ * makes each of them, or does not.
+ */
+export interface AiJobOutput {
+    resource: AiJobOutputResource;
+    id: string;
+    /** The unpublished version the job created, where the resource has versions. */
+    versionId?: string | null;
+    /** `null` for an output that belongs to the org rather than one site. */
+    hostId: string | null;
+    /**
+     * The site's subdomain, which is what a console URL names a site by: the
+     * `[host]` segment resolves by subdomain, so a link built from `hostId`
+     * names no site the console can open.
+     */
+    hostSubdomain?: string | null;
+    label: string;
+    /** The body of a `text` output. Absent on every other resource. */
+    text?: string;
+    /**
+     * The change set of an output a person applies rather than opens — a
+     * `theme` or `seo` proposal — in the shape its job kind's runner defines.
+     */
+    proposal?: Record<string, unknown>;
+    /**
+     * What the person decides next about this output, in customer-safe words:
+     * a routing the draft could not store, or part of the brief it could not
+     * build. Absent when there is nothing to decide.
+     */
+    note?: string | null;
+    /**
+     * What a first visit is estimated to transfer, as the doctrine measured
+     * the generated document (AGL-2935) — the weight the proposal shows before
+     * anything is applied. Absent where the output is not a page's document.
+     */
+    load?: AiLoadEstimate | null;
+}
+export interface AiJobLease {
+    /** The process that holds the step: a route request id or a beat id. */
+    owner: string;
+    until: ITimestamp;
+}
+/** Why a job stopped for a person (AGL-2935). */
+export type AiJobReviewReason = 
+/** The plan step proposed a plan; generation waits for it to be confirmed. */
+'plan'
+/** An answer broke a building rule, and so did the answer to the re-ask. */
+ | 'doctrine'
+/**
+ * The site is at an allowance its plan sets for what the step writes, such
+ * as its shared layouts or its templates (AGL-2909). Freeing one, or a plan
+ * that holds more, is the member's decision; trying again runs the step
+ * again.
+ */
+ | 'limit';
+/**
+ * A building rule an answer broke, as the job keeps it: the number, the code,
+ * the sentence, and where in the answer it was broken (AGL-3078).
+ */
+export interface AiJobRuleFinding {
+    rule: number | null;
+    code: string;
+    /** Customer-safe. */
+    message: string;
+    /** The nodes the finding names, by the ids the refused answer gave them. Absent when it names none. */
+    nodeIds?: string[];
+    /** The plan entries or answer fields it names, as `screens[0].sections[2]`. Absent when it names none. */
+    paths?: string[];
+}
+/**
+ * One node of the parts of a refused answer its findings name (AGL-3078), as
+ * the review keeps it: the node's place, its element and the names of what it
+ * sets, and never its copy. A Grid keeps the values of its layout props as
+ * they were written, so a review can tell a shape the rules refuse from one
+ * the model was asked to mend and did not.
+ */
+export interface AiJobReviewOutlineNode {
+    /** The node's id, as the refused answer wrote it. */
+    id: string;
+    /** How far below a node a finding names it sits: 0 for that node. */
+    depth: number;
+    componentId: string;
+    /** The props it sets, by name only. */
+    props: string[];
+    /** The `sx` keys it sets, by name only; absent when it sets none. */
+    sx?: string[];
+    /** A Grid's layout props, `container`, `size`, `direction`, `spacing` and the rest, as written. */
+    grid?: Record<string, string | number | boolean | null>;
+    /** Its children's element ids, in order. */
+    children: string[];
+}
+export interface AiJobReview {
+    reason: AiJobReviewReason;
+    /** Customer-safe: what the person is asked to decide. */
+    message: string;
+    /** The rules the last answer broke; empty for a plan. */
+    findings: AiJobRuleFinding[];
+    /**
+     * The parts of the refused answer its findings name, each node with the
+     * nodes below it (AGL-3078); absent when they name none. Kept with the job
+     * for diagnosis, and shown to staff.
+     */
+    outline?: AiJobReviewOutlineNode[];
+}
+export type AiJobPlanStatus = 'proposed' | 'confirmed';
+/** The plan a job builds from, as the job keeps it once its plan step proposed it. */
+export interface AiJobPlan extends AiBuildPlan {
+    status: AiJobPlanStatus;
+    /** Names for the inventory ids the plan references, read when it was made. */
+    labels: Record<string, string>;
+    proposedAt: ITimestamp;
+    confirmedAt: ITimestamp | null;
+    /** The member who confirmed it. */
+    confirmedBy: string | null;
+    /**
+     * A digest of the whole request that produced this plan (AGL-2937): the
+     * job's kind, site, brief and scalar inputs, the model that answered, and
+     * the prompt as it was rendered — the site inventory included. A later job
+     * whose request hashes the same reuses this plan rather than paying for the
+     * same answer again. A hash of the request, never of the answer, and no
+     * part of the brief is recoverable from it.
+     */
+    key?: string;
+    /** The job this plan was reused from, when it was not asked for again. */
+    reusedFrom?: string;
+}
+export interface AiJob {
+    $id: string;
+    orgId: string;
+    hostId?: string | null;
+    kind: AiJobKind;
+    status: AiJobStatus;
+    /** The customer's brief, verbatim. Expires with the document. */
+    brief: string;
+    /** Kind-specific inputs the runner reads (a screen id to edit, a tone). */
+    inputs: Record<string, unknown>;
+    /**
+     * The model the creator picked for the job's steps (AGL-2942), or `null`
+     * for Auto. Each step honors it only where the plan and the allotment
+     * allowlists allow it, and runs on the routing table otherwise.
+     */
+    model?: string | null;
+    steps: AiJobStep[];
+    outputs: AiJobOutput[];
+    /**
+     * The nominal credit figure held against the job while steps are
+     * outstanding. The meter's real bound is the per-step message reservation
+     * and the org's monthly ceiling; this is the number the console shows so
+     * a running job is not read as free.
+     */
+    creditsReserved: number;
+    creditsSpent: number;
+    createdBy: string;
+    createdAt: ITimestamp;
+    updatedAt: ITimestamp;
+    /** TTL — the brief is verbatim customer text and expires like an exchange. */
+    expiresAt: ITimestamp;
+    /** Customer-safe only. */
+    error?: string | null;
+    lease?: AiJobLease | null;
+    /** The plan the job builds from, once its plan step proposed one. */
+    plan?: AiJobPlan | null;
+    /** What the person is asked to decide while the job is `needs_review`. */
+    review?: AiJobReview | null;
+    /**
+     * What a person applied from the job's outputs (AGL-2910). Written by the
+     * door that applied them, never by a step runner, and absent until then.
+     */
+    applied?: AiJobApplied | null;
+}
+/**
+ * The record of an apply (AGL-2910): what became a new unpublished version,
+ * and what waits in its editor for a person to save.
+ */
+export interface AiJobApplied {
+    at: ITimestamp;
+    /** The member who applied. */
+    by: string;
+    /** The new version opened for each resource, by resource id. */
+    versions: Record<string, string>;
+    /** Resource ids whose proposed values wait in their editor, unsaved. */
+    staged: string[];
+}
+/** The plan on the wire: every instant an ISO string. */
+export interface AiJobPlanSummary extends AiBuildPlan {
+    status: AiJobPlanStatus;
+    labels: Record<string, string>;
+    proposedAt: string | null;
+    confirmedAt: string | null;
+    confirmedBy: string | null;
+    key?: string;
+    reusedFrom?: string;
+}
+/**
+ * The wire form the console reads: every instant an ISO string, the lease
+ * reduced to whether a runner holds the job. The brief and the outputs
+ * travel as they are — the reader is a member of the org that wrote them.
+ */
+export interface AiJobSummary {
+    id: string;
+    orgId: string;
+    hostId: string | null;
+    kind: AiJobKind;
+    status: AiJobStatus;
+    brief: string;
+    /**
+     * The batch a door created this job as one of (AGL-2911), read off the
+     * job's inputs; `null` for a job created on its own. The console groups a
+     * run of jobs by it, which is the one thing it cannot do from a list whose
+     * rows carry no inputs — and the only input the wire form carries, because
+     * a batch id names nothing the member wrote.
+     */
+    batch: string | null;
+    steps: Array<{
+        name: string;
+        status: AiJobStepStatus;
+        startedAt: string | null;
+        endedAt: string | null;
+        creditsSpent: number;
+        error: string | null;
+    }>;
+    outputs: AiJobOutput[];
+    creditsReserved: number;
+    creditsSpent: number;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+    error: string | null;
+    running: boolean;
+    plan: AiJobPlanSummary | null;
+    review: AiJobReview | null;
+    /** What a person applied from the outputs (AGL-2910); instants as ISO strings. */
+    applied?: {
+        at: string | null;
+        by: string;
+        versions: Record<string, string>;
+        staged: string[];
+    } | null;
+}

package/src/lib/model/ai-jobs.types.js

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /** The union as a value, so a route can validate a body against it. */ export const AI_JOB_KINDS = [
+    'page',
+    'component',
+    'layout',
+    'template',
+    'edit',
+    'seo',
+    'site',
+    'email',
+    'campaign',
+    'form',
+    'experiment',
+    'insight',
+    'products',
+    'crm',
+    'onboarding',
+    'workflow',
+    'text',
+    'theme'
+];
+export const AI_JOB_TERMINAL_STATUSES = [
+    'done',
+    'failed',
+    'canceled'
+];
+
+//# sourceMappingURL=ai-jobs.types.js.map

package/src/lib/model/ai-jobs.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-jobs.types.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type { AiEffort } from '../providers/contract'\nimport type { AiLoadEstimate } from '../runtime/ai-palette'\nimport type { AiBuildPlan } from './ai-build-plan'\n\n/**\n * AI generation jobs (AGL-2904).\n *\n * A job is one customer brief carried through one or more model steps by a\n * Firestore state machine, so that work longer than a request can survive\n * the request: the console route runs what it can inline, and the platform\n * job beat resumes whatever is left. The document is the whole state — no\n * process holds anything the next beat cannot read back.\n *\n * ── Outputs are drafts, never a publish ──────────────────────────────────\n *\n * Every output a job produces is a NEW draft or a new unpublished version of\n * an existing resource. A job never flips a version pointer, never registers\n * a route and never sends anything; a person opens the draft the job names\n * and publishes it through the door that already exists for that resource.\n * That is what lets a job run with no visitor, no session and no confirm\n * gate — the thing it writes cannot be seen by anyone but the workspace\n * until a member chooses otherwise.\n *\n * ── The lease ────────────────────────────────────────────────────────────\n *\n * A step runs under a lease: an owner id and an `until` instant. Two beats\n * fire a minute apart against a 120 s function timeout, and a console route\n * may still be running the first step when the first beat looks, so the\n * lease is what stops the same step being run — and metered — twice. A\n * claim is a transaction that refuses while another owner's lease is live;\n * an expired lease is simply claimable, which is also how a step abandoned\n * by a frozen process is recovered.\n */\n\n/**\n * What a job produces. `text` and `theme` have runners; every other kind is\n * registered and refuses with \"not available yet\" until its own issue lands,\n * so a kind's presence in the union says the job model accepts it, not that\n * a runner exists.\n */\nexport type AiJobKind =\n  | 'page'\n  | 'component'\n  | 'layout'\n  | 'template'\n  | 'edit'\n  | 'seo'\n  | 'site'\n  | 'email'\n  | 'campaign'\n  | 'form'\n  | 'experiment'\n  | 'insight'\n  | 'products'\n  | 'crm'\n  | 'onboarding'\n  | 'workflow'\n  | 'text'\n  | 'theme'\n\n/** The union as a value, so a route can validate a body against it. */\nexport const AI_JOB_KINDS: readonly AiJobKind[] = [\n  'page',\n  'component',\n  'layout',\n  'template',\n  'edit',\n  'seo',\n  'site',\n  'email',\n  'campaign',\n  'form',\n  'experiment',\n  'insight',\n  'products',\n  'crm',\n  'onboarding',\n  'workflow',\n  'text',\n  'theme',\n]\n\n/**\n * `queued` — waiting for a runner; `running` — a step holds the lease;\n * `needs_input` — the job stopped for something only the workspace can\n * change (credits, a cap, a switch), and the beat tries it again once that\n * may have changed; `needs_review` — the job stopped for a person's decision\n * (AGL-2935): its plan is ready to confirm, or an answer broke a building\n * rule on its re-ask. No timer can make that decision, so neither the beat\n * nor anything but that person resumes it. The last three are terminal.\n */\nexport type AiJobStatus =\n  | 'queued'\n  | 'running'\n  | 'needs_input'\n  | 'needs_review'\n  | 'done'\n  | 'failed'\n  | 'canceled'\n\nexport const AI_JOB_TERMINAL_STATUSES: readonly AiJobStatus[] = [\n  'done',\n  'failed',\n  'canceled',\n]\n\nexport type AiJobStepStatus = 'pending' | 'running' | 'done' | 'failed'\n\nexport interface AiJobStep {\n  /** Stable within the job (`plan`, `draft`, `generate`), unique per job. */\n  name: string\n  status: AiJobStepStatus\n  startedAt?: ITimestamp | null\n  endedAt?: ITimestamp | null\n  /** Credits this step has actually cost, at the plan's credit rate. */\n  creditsSpent: number\n  /** Customer-safe only; provider detail goes to the server log. */\n  error?: string | null\n  /**\n   * How many times a runner has been handed this step. A retryable provider\n   * failure hands the step back as `pending`; the count is what stops a\n   * provider outage re-running a step forever.\n   */\n  attempts?: number\n  /**\n   * Passes of a step that works through a list (AGL-2910): each one a\n   * recorded, metered exchange that asked to continue. Attempts count again\n   * from zero after a pass; this count is what bounds the step.\n   */\n  passes?: number\n  /**\n   * What the step's model calls cost in tokens and time (AGL-2937), summed\n   * over every run that reached the provider. Absent on a step none has.\n   */\n  tokens?: AiJobStepTokens\n  /**\n   * The ids the step writes its drafts under, by draft (AGL-3079): minted\n   * when the job is created, so every run of the step names the same drafts.\n   * Absent on a step that writes none; a step that records none names its\n   * drafts by the job's own id.\n   */\n  draftIds?: Partial<Record<AiJobDraftSlot, string>>\n}\n\n/**\n * A draft a job's kind always writes (AGL-3079): a screen, layout, template,\n * form or component; an email design; a campaign; an automation.\n */\nexport type AiJobDraftSlot =\n  | 'screen'\n  | 'layout'\n  | 'template'\n  | 'form'\n  | 'component'\n  | 'email'\n  | 'campaign'\n  | 'workflow'\n\n/**\n * A step's measure (AGL-2937): the four token counts the meter prices, the\n * time spent in the runner, and the model and thinking effort of the last\n * run. The machine writes it beside `creditsSpent`, so what a kind of step\n * costs in tokens is read off the job rather than inferred from the month.\n */\nexport interface AiJobStepTokens {\n  /** Prompt tokens sent uncached. */\n  input: number\n  /** Prompt tokens read from the prompt cache. */\n  cachedRead: number\n  /** Prompt tokens written to the prompt cache. */\n  cacheWrite: number\n  /** Tokens generated, thinking included. */\n  output: number\n  /** The model the last run was served by. */\n  model: string | null\n  /** The thinking effort the last run asked for; `null` when it named none. */\n  effort: AiEffort | null\n  /** Milliseconds spent in the runner, summed over runs. */\n  latencyMs: number\n  /** Runs that reached the provider. */\n  runs: number\n  /**\n   * Why the step's latest runs stopped (AGL-3042), oldest first and the last\n   * run last: each run's stop reason and the tokens it generated, so a pass\n   * cut off at its ceiling reads off the job rather than out of the sums. At\n   * most `AI_JOB_STEP_LAST_RUNS` are kept; absent on a step measured before.\n   */\n  lastRuns?: AiJobStepRunStop[]\n}\n\n/** One run of a step, by why it stopped (AGL-3042). */\nexport interface AiJobStepRunStop {\n  /**\n   * The stop reason of the run's last model call — `tool_use` or `end_turn`\n   * for an answer, `max_tokens` for one cut off at its ceiling, `refusal` —\n   * and `null` when the provider named none.\n   */\n  stopReason: string | null\n  /** Tokens the run generated, over every model call it made. */\n  output: number\n}\n\nexport type AiJobOutputResource =\n  | 'screen'\n  | 'reusableComponent'\n  | 'layout'\n  | 'template'\n  | 'form'\n  | 'emailScreen'\n  | 'campaign'\n  | 'product'\n  | 'experiment'\n  | 'workflow'\n  | 'text'\n  | 'theme'\n  | 'seo'\n  | 'insight'\n  | 'crm'\n\n/**\n * One thing a job wrote. Addressed by resource and id so the console can\n * build the \"open draft\" link without knowing what the runner did; `text`\n * has no document of its own, so its body rides on the output itself.\n *\n * A `theme` output is a proposal rather than a document (AGL-2938). A site's\n * theme is fields on its host document, and writing those fields is the save\n * the Theme section's editor performs, which a job never does. So the change\n * set rides on the output as `proposal`, and a person puts it in the editor\n * and saves it there, or does not.\n *\n * An `seo` output is a proposal rather than a document (AGL-2910): search\n * listing values for a page or a product, or a site audit's findings and\n * fixes. A screen's listing is served from the screen document itself, so a\n * job never writes it; the values ride on the output as `proposal`, a person\n * puts them in the editor and saves them there, and an audit's content fixes\n * become new versions only when a person applies them.\n *\n * A `crm` output is a proposal too (AGL-2917): a record's summary and next\n * step, an email draft, or an import's column matches. The CRM's own task\n * form, stage route, composer and import drawer are the writes, and a person\n * makes each of them, or does not.\n */\nexport interface AiJobOutput {\n  resource: AiJobOutputResource\n  id: string\n  /** The unpublished version the job created, where the resource has versions. */\n  versionId?: string | null\n  /** `null` for an output that belongs to the org rather than one site. */\n  hostId: string | null\n  /**\n   * The site's subdomain, which is what a console URL names a site by: the\n   * `[host]` segment resolves by subdomain, so a link built from `hostId`\n   * names no site the console can open.\n   */\n  hostSubdomain?: string | null\n  label: string\n  /** The body of a `text` output. Absent on every other resource. */\n  text?: string\n  /**\n   * The change set of an output a person applies rather than opens — a\n   * `theme` or `seo` proposal — in the shape its job kind's runner defines.\n   */\n  proposal?: Record<string, unknown>\n  /**\n   * What the person decides next about this output, in customer-safe words:\n   * a routing the draft could not store, or part of the brief it could not\n   * build. Absent when there is nothing to decide.\n   */\n  note?: string | null\n  /**\n   * What a first visit is estimated to transfer, as the doctrine measured\n   * the generated document (AGL-2935) — the weight the proposal shows before\n   * anything is applied. Absent where the output is not a page's document.\n   */\n  load?: AiLoadEstimate | null\n}\n\nexport interface AiJobLease {\n  /** The process that holds the step: a route request id or a beat id. */\n  owner: string\n  until: ITimestamp\n}\n\n/** Why a job stopped for a person (AGL-2935). */\nexport type AiJobReviewReason =\n  /** The plan step proposed a plan; generation waits for it to be confirmed. */\n  | 'plan'\n  /** An answer broke a building rule, and so did the answer to the re-ask. */\n  | 'doctrine'\n  /**\n   * The site is at an allowance its plan sets for what the step writes, such\n   * as its shared layouts or its templates (AGL-2909). Freeing one, or a plan\n   * that holds more, is the member's decision; trying again runs the step\n   * again.\n   */\n  | 'limit'\n\n/**\n * A building rule an answer broke, as the job keeps it: the number, the code,\n * the sentence, and where in the answer it was broken (AGL-3078).\n */\nexport interface AiJobRuleFinding {\n  rule: number | null\n  code: string\n  /** Customer-safe. */\n  message: string\n  /** The nodes the finding names, by the ids the refused answer gave them. Absent when it names none. */\n  nodeIds?: string[]\n  /** The plan entries or answer fields it names, as `screens[0].sections[2]`. Absent when it names none. */\n  paths?: string[]\n}\n\n/**\n * One node of the parts of a refused answer its findings name (AGL-3078), as\n * the review keeps it: the node's place, its element and the names of what it\n * sets, and never its copy. A Grid keeps the values of its layout props as\n * they were written, so a review can tell a shape the rules refuse from one\n * the model was asked to mend and did not.\n */\nexport interface AiJobReviewOutlineNode {\n  /** The node's id, as the refused answer wrote it. */\n  id: string\n  /** How far below a node a finding names it sits: 0 for that node. */\n  depth: number\n  componentId: string\n  /** The props it sets, by name only. */\n  props: string[]\n  /** The `sx` keys it sets, by name only; absent when it sets none. */\n  sx?: string[]\n  /** A Grid's layout props, `container`, `size`, `direction`, `spacing` and the rest, as written. */\n  grid?: Record<string, string | number | boolean | null>\n  /** Its children's element ids, in order. */\n  children: string[]\n}\n\nexport interface AiJobReview {\n  reason: AiJobReviewReason\n  /** Customer-safe: what the person is asked to decide. */\n  message: string\n  /** The rules the last answer broke; empty for a plan. */\n  findings: AiJobRuleFinding[]\n  /**\n   * The parts of the refused answer its findings name, each node with the\n   * nodes below it (AGL-3078); absent when they name none. Kept with the job\n   * for diagnosis, and shown to staff.\n   */\n  outline?: AiJobReviewOutlineNode[]\n}\n\nexport type AiJobPlanStatus = 'proposed' | 'confirmed'\n\n/** The plan a job builds from, as the job keeps it once its plan step proposed it. */\nexport interface AiJobPlan extends AiBuildPlan {\n  status: AiJobPlanStatus\n  /** Names for the inventory ids the plan references, read when it was made. */\n  labels: Record<string, string>\n  proposedAt: ITimestamp\n  confirmedAt: ITimestamp | null\n  /** The member who confirmed it. */\n  confirmedBy: string | null\n  /**\n   * A digest of the whole request that produced this plan (AGL-2937): the\n   * job's kind, site, brief and scalar inputs, the model that answered, and\n   * the prompt as it was rendered — the site inventory included. A later job\n   * whose request hashes the same reuses this plan rather than paying for the\n   * same answer again. A hash of the request, never of the answer, and no\n   * part of the brief is recoverable from it.\n   */\n  key?: string\n  /** The job this plan was reused from, when it was not asked for again. */\n  reusedFrom?: string\n}\n\nexport interface AiJob {\n  $id: string\n  orgId: string\n  hostId?: string | null\n  kind: AiJobKind\n  status: AiJobStatus\n  /** The customer's brief, verbatim. Expires with the document. */\n  brief: string\n  /** Kind-specific inputs the runner reads (a screen id to edit, a tone). */\n  inputs: Record<string, unknown>\n  /**\n   * The model the creator picked for the job's steps (AGL-2942), or `null`\n   * for Auto. Each step honors it only where the plan and the allotment\n   * allowlists allow it, and runs on the routing table otherwise.\n   */\n  model?: string | null\n  steps: AiJobStep[]\n  outputs: AiJobOutput[]\n  /**\n   * The nominal credit figure held against the job while steps are\n   * outstanding. The meter's real bound is the per-step message reservation\n   * and the org's monthly ceiling; this is the number the console shows so\n   * a running job is not read as free.\n   */\n  creditsReserved: number\n  creditsSpent: number\n  createdBy: string\n  createdAt: ITimestamp\n  updatedAt: ITimestamp\n  /** TTL — the brief is verbatim customer text and expires like an exchange. */\n  expiresAt: ITimestamp\n  /** Customer-safe only. */\n  error?: string | null\n  lease?: AiJobLease | null\n  /** The plan the job builds from, once its plan step proposed one. */\n  plan?: AiJobPlan | null\n  /** What the person is asked to decide while the job is `needs_review`. */\n  review?: AiJobReview | null\n  /**\n   * What a person applied from the job's outputs (AGL-2910). Written by the\n   * door that applied them, never by a step runner, and absent until then.\n   */\n  applied?: AiJobApplied | null\n}\n\n/**\n * The record of an apply (AGL-2910): what became a new unpublished version,\n * and what waits in its editor for a person to save.\n */\nexport interface AiJobApplied {\n  at: ITimestamp\n  /** The member who applied. */\n  by: string\n  /** The new version opened for each resource, by resource id. */\n  versions: Record<string, string>\n  /** Resource ids whose proposed values wait in their editor, unsaved. */\n  staged: string[]\n}\n\n/** The plan on the wire: every instant an ISO string. */\nexport interface AiJobPlanSummary extends AiBuildPlan {\n  status: AiJobPlanStatus\n  labels: Record<string, string>\n  proposedAt: string | null\n  confirmedAt: string | null\n  confirmedBy: string | null\n  key?: string\n  reusedFrom?: string\n}\n\n/**\n * The wire form the console reads: every instant an ISO string, the lease\n * reduced to whether a runner holds the job. The brief and the outputs\n * travel as they are — the reader is a member of the org that wrote them.\n */\nexport interface AiJobSummary {\n  id: string\n  orgId: string\n  hostId: string | null\n  kind: AiJobKind\n  status: AiJobStatus\n  brief: string\n  /**\n   * The batch a door created this job as one of (AGL-2911), read off the\n   * job's inputs; `null` for a job created on its own. The console groups a\n   * run of jobs by it, which is the one thing it cannot do from a list whose\n   * rows carry no inputs — and the only input the wire form carries, because\n   * a batch id names nothing the member wrote.\n   */\n  batch: string | null\n  steps: Array<{\n    name: string\n    status: AiJobStepStatus\n    startedAt: string | null\n    endedAt: string | null\n    creditsSpent: number\n    error: string | null\n  }>\n  outputs: AiJobOutput[]\n  creditsReserved: number\n  creditsSpent: number\n  createdBy: string\n  createdAt: string\n  updatedAt: string\n  error: string | null\n  running: boolean\n  plan: AiJobPlanSummary | null\n  review: AiJobReview | null\n  /** What a person applied from the outputs (AGL-2910); instants as ISO strings. */\n  applied?: {\n    at: string | null\n    by: string\n    versions: Record<string, string>\n    staged: string[]\n  } | null\n}\n"],"names":["AI_JOB_KINDS","AI_JOB_TERMINAL_STATUSES"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA+DD,qEAAqE,GACrE,OAAO,MAAMA,eAAqC;IAChD;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAoBD,OAAO,MAAMC,2BAAmD;IAC9D;IACA;IACA;CACD,CAAA"}

package/src/lib/model/ai-page-job.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AiBuildPlan, type AiBuildPlanCreateKind } from './ai-build-plan';
+import type { AiPlanUncreatable } from './ai-plan-capabilities';
+/**
+ * What a page job is (AGL-2907): the page types a brief may name, the inputs
+ * the job doors admit, and the plans a page generator can build.
+ *
+ * A page job builds ONE screen. It places the site's components by id, binds
+ * its forms by id, and renders inside a layout — and since AGL-3031 it first
+ * builds the layout, forms and components its own plan creates, in the same
+ * job, through the steps that own them, so a doctrine-correct plan is one it
+ * finishes rather than one it sends the member away from. Anything else a
+ * plan creates — a template, a theme change, a dataset, an email — is another
+ * job's work, and such a plan is refused before anything is spent, with a
+ * sentence naming what to make first.
+ *
+ * This module imports nothing at runtime, so the doors, the step, the console
+ * dialog and the specs read one vocabulary.
+ */
+export type AiPageType = 'landing' | 'about' | 'pricing' | 'contact' | 'blogIndex' | 'product' | 'service' | 'event';
+export interface AiPageTypeDefinition {
+    id: AiPageType;
+    /** The chip's label in the Describe dialog. */
+    label: string;
+    /** What the page is for, as the plan and the generation are told. */
+    purpose: string;
+}
+export declare const AI_PAGE_TYPES: readonly AiPageTypeDefinition[];
+/** The definition of a page type id, or `null` for anything else. */
+export declare function aiPageTypeDefinition(id: unknown): AiPageTypeDefinition | null;
+export interface AiPageJobInputs {
+    /** The type the member picked; `null` when they picked none. */
+    pageType: AiPageType | null;
+}
+/** A page job's inputs, or the sentence the door refuses them with. */
+export declare function parseAiPageJobInputs(inputs: Readonly<Record<string, unknown>> | null | undefined): AiPageJobInputs | string;
+/** A creation a plan names, as the refusal lists it. */
+export interface AiPagePrerequisite {
+    kind: AiBuildPlanCreateKind;
+    name: string;
+}
+/**
+ * What the plan asks to be created that a page job does not build, in the
+ * order the plan lists it, each named once: every entry is something a
+ * member makes first.
+ */
+export declare function aiPagePlanPrerequisites(plan: AiBuildPlan): AiPagePrerequisite[];
+/**
+ * The creations a page job builds itself from its own plan (AGL-3031): the
+ * layout the page renders inside, and the forms and components it places.
+ * Each is built before the page, as a draft, by the step that builds that
+ * kind on its own. The plan step is told this list before it answers, and
+ * the plan rules refuse a creation outside it with the one re-ask every rule
+ * gets, so a plan that needs another never reaches a member's Confirm.
+ */
+export declare const AI_PAGE_CREATE_KINDS: readonly AiBuildPlanCreateKind[];
+/**
+ * Why a page job cannot build a plan of this SHAPE — no page, several pages,
+ * a page with no sections — in a sentence a member reads; `null` when the
+ * shape is one it builds. The plan step holds a plan to it with a re-ask, and
+ * the doors hold a confirmed plan to it again through `aiPagePlanRefusal`.
+ */
+export declare function aiPagePlanShapeRefusal(plan: AiBuildPlan): string | null;
+/**
+ * Why a page job cannot build this plan, in a sentence a member reads when
+ * confirming it; `null` when it can. A page job builds exactly one screen,
+ * from what the site already has.
+ */
+export declare function aiPagePlanRefusal(plan: AiBuildPlan): string | null;
+/**
+ * Why a page job cannot build the creations its plan names ON THIS SITE NOW,
+ * in a sentence a member reads when confirming it: what the workspace's plan
+ * does not include, or what the site has no room left for. The plan step was
+ * told what could be created, so this is the site changing between the plan
+ * and its confirmation.
+ */
+export declare function aiPageCreationRefusal(refused: readonly AiPlanUncreatable[]): string | null;