@nocobase/app-plugin-agents 0.0.0-stage → 0.1.0-beta.10

package/dist/server/core/runs/ports.d.ts

@@ -0,0 +1,253 @@
+/**
+ * What the runs domain needs from the domain a run works on, and tells it. The runs domain knows a subject only as
+ * `{ kind, id }`; the application that owns the kind registers a binding for it (this plugin registers its own
+ * `conversation`).
+ */
+import type { RunInput, WorkspaceDir, WorkspaceCommitEvidence } from '@nocobase/agent-protocol';
+import type { DatabaseConnection } from '@nocobase/db';
+import type { Agent } from '../../../shared/agents.js';
+import type { I18nText } from '../../../shared/i18n.js';
+import type { Runner } from '../../../shared/runners.js';
+import type { Run } from '../../../shared/runs.js';
+import type { Tx } from '../../kernel/tx.js';
+/** A command as a brief names it: `` `acme issue get` ``, with a flag named in `flag` after it (`--file`). */
+export declare function commandRef(cli: string, commandId: string, flag?: string): string;
+/** What a claim (or a brief preview, without a runner) hands the subject's domain. */
+export interface ClaimContext {
+    readonly run: Run;
+    readonly agent: Agent;
+    /** The runner claiming; null for a preview. */
+    readonly runner: Runner | null;
+    /** The run's input not yet handled, oldest first. */
+    readonly inputs: readonly RunInput[];
+    /** The application CLI command the agent talks to the application with (`acme`). */
+    readonly cli: string;
+    /** The application's name in prose (`agents.app.name`, such as `Acme`). */
+    readonly appName: string;
+}
+/**
+ * A working directory of the subject, in order (the first is the primary one): a git repository to check out, or a
+ * directory already on one runner (`runnerId`), used as it is, which only that runner may take. `scopeId` is where the
+ * directory's own variables and default skills are kept (scope `workdir`), when it has any.
+ */
+export type SubjectDir = WorkspaceDir & {
+    readonly scopeId?: string;
+    readonly runnerId?: string;
+};
+/** Where the subject keeps variables and default skills beyond its directories': the group it belongs to, say. */
+export interface SubjectScope {
+    /** A scope key the application registered (`agents.scopes`). */
+    readonly scope: string;
+    readonly scopeId: string;
+}
+/** The subject's part of a run payload; the runs domain adds the rules, the workspace and the skills. */
+export interface SubjectAssembly {
+    /**
+     * `key` names the run's working directory (and a checkout's branch, as the subject's domain chooses); `title` and
+     * `url` are what a person sees of the subject; `noun` is what the brief calls it (`ticket`, `document`).
+     */
+    readonly subject: {
+        readonly key: string;
+        readonly title?: string;
+        readonly url: string;
+        readonly noun: string;
+    };
+    /**
+     * The brief's system layer, when the subject's runs follow other rules altogether (a conversation answers in its own
+     * text). Absent: the platform's rules for working on a subject, with `guidance`.
+     */
+    readonly system?: string;
+    /**
+     * The subject's own lines of the platform's rules: how the agent reports progress and results, and which moves it may
+     * make (`rules`, each one line of the rules list), and what it does when it cannot get the environment working
+     * (`whenBlocked`, one line of the environment check). Absent: the agent says so in its last message.
+     */
+    readonly guidance?: {
+        readonly rules: readonly string[];
+        readonly whenBlocked?: string;
+    };
+    /** The brief's task layer: why the agent runs now and how to finish. */
+    readonly task: string;
+    /** The brief's context layer: the subject as it is now. */
+    readonly context: string;
+    /** Effective inputs selected by the subject for this turn; absent, deliver all claim inputs. */
+    readonly inputs?: readonly RunInput[];
+    readonly turn: {
+        readonly prompt: string;
+        readonly previousSummary?: string;
+        /**
+         * Added to a runner's turn once the claim knows whether the tool's session resumes (`resumed`) or starts fresh
+         * (`fresh`): what is new since the agent's last run, say, which only a resumed session can rely on.
+         */
+        readonly resumed?: string;
+        readonly fresh?: string;
+    };
+    /** Passed to the agent unchanged (`acme run context`). */
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly dirs: readonly SubjectDir[];
+    /**
+     * Scopes whose variables and default skills the run also gets, before its directories' (the group it belongs to):
+     * variables merge these scopes, in order < directories < agent.
+     */
+    readonly scopes: readonly SubjectScope[];
+    /**
+     * The runner's work directory for this run in place of the subject's (`RunWorkspace.key`), such as a coordinating
+     * agent's that checks nothing out and so never waits for the subject's lock. Letters, digits, `.`, `_` and `-`.
+     */
+    readonly workspaceKey?: string;
+    /**
+     * The run only reads (a review, reading a failed check): the runner gives it a work directory of its own with the
+     * same branches checked out and pushes nothing (`RunWorkspace.readOnly`), so it runs alongside the run that writes.
+     */
+    readonly readOnly?: boolean;
+}
+export interface ContextProvider {
+    /** Read external permissions before the claim transaction; assembly receives this result as its third argument. */
+    prepare?(run: Run): Promise<unknown>;
+    /**
+     * Optional subject policy, checked when queued work is claimed, inside that transaction and before assembly.
+     * Return a rejection to cancel this run normally: no payload, token, failure count, or retry is produced. Throwing
+     * remains an assembly failure. Also asked before input is appended to or delivered to a working run, where a
+     * rejection keeps the input from that run. Not called for previews or reading an already working run's context.
+     */
+    admit?(conn: DatabaseConnection, claim: ClaimContext): Promise<{
+        readonly reason: string;
+        readonly detail?: string;
+    } | null>;
+    /**
+     * Optional input policy: of `claim.inputs`, the ones this turn should act on. Applied, with `admit`, when input is
+     * appended to a working run and when it is delivered to one; what it leaves out is marked handled, never delivered.
+     * The claim keeps using `SubjectAssembly.inputs`. Absent, every input is delivered.
+     */
+    selectInputs?(conn: DatabaseConnection, claim: ClaimContext): Promise<readonly RunInput[]>;
+    /**
+     * Called inside the claim's transaction, again for `GET /api/agents/runs/current/context`, and for a brief preview (a run
+     * that is not stored, and no runner). Database reads only: no network, no model. Throwing leaves the run queued; a
+     * run that fails to assemble three times fails `setupFailed`.
+     */
+    assemble(conn: DatabaseConnection, claim: ClaimContext, prepared?: unknown): Promise<SubjectAssembly>;
+}
+/**
+ * A made-up subject of a kind, for "Preview full prompt": what a run on one would be told, without a real one. Every
+ * made-up value is marked with `sampleValue`, so nobody mistakes it for data.
+ */
+export interface SubjectSample {
+    /**
+     * The assembly of the made-up subject, as `ContextProvider.assemble` would give it for a real one. Database reads only,
+     * and never of a subject: the application's own settings at most. `claim.run.subject.id` is `sample`.
+     */
+    assemble(conn: DatabaseConnection, claim: ClaimContext): Promise<SubjectAssembly>;
+    /**
+     * What wakes the agent on it, as the run's inputs; without it, one signal saying the previewing person gave it the
+     * subject.
+     */
+    inputs?(user: {
+        readonly id: string;
+        readonly name: string;
+    }, at: string): readonly RunInput[];
+}
+export interface WorkSink {
+    /**
+     * In the transaction that ended the run: completed, cancelled, or failed with no attempt left. A failed run's
+     * `failureReason` says why; this is where the subject's domain asks people what next (retry, reassign, cancel).
+     */
+    onRunFinished?(tx: Tx, run: Run): Promise<void>;
+}
+/** What the reports know of one subject. */
+export interface SubjectFacts {
+    /** What a person reads for it (`TKT-12 Retry callbacks`). */
+    readonly label: string;
+    /** Whether the person asking may see it; runs on a subject they may not see are left out of their reports. */
+    readonly visible: boolean;
+    /** The group it belongs to, which the reports group and filter by. */
+    readonly group: {
+        readonly id: string;
+        readonly name: string;
+    } | null;
+}
+/** Whether the work on subjects of a kind is over (`SubjectBinding.workspaces`). */
+export interface SubjectWorkspaces {
+    /**
+     * The subjects a directory's key names (`TASK-42`), for a directory without a run the application knows: each key
+     * with every subject it may name, so an ambiguous key is left alone. A subject that is gone names none.
+     */
+    resolveKeys?(conn: DatabaseConnection, keys: readonly string[]): Promise<ReadonlyMap<string, readonly string[]>>;
+    /**
+     * @deprecated No longer read: a directory of a subject whose work is over is removed without commits proving its
+     * pushes, and runners are always told none.
+     */
+    commits?(conn: DatabaseConnection, subjectIds: readonly string[]): Promise<ReadonlyMap<string, readonly WorkspaceCommitEvidence[]>>;
+    /**
+     * Of `subjectIds` (of the binding's kind, each at most once), the ones whose work is over, such as a ticket that is
+     * done or cancelled: runners remove the working directories they keep for them, whatever those still hold. Ids it does not know, or cannot decide, are left out; they are kept. Read inside `conn`, without writing.
+     */
+    settled(conn: DatabaseConnection, subjectIds: readonly string[]): Promise<ReadonlySet<string>>;
+}
+export interface SubjectReports {
+    describe(conn: DatabaseConnection, userId: string, ids: readonly string[]): Promise<ReadonlyMap<string, SubjectFacts>>;
+}
+export interface SubjectBinding {
+    readonly kind: string;
+    /** Overrides execution identity for selected work. Undefined preserves the caller's identity; a null actorUserId refuses it.
+     * Read in the enqueue/claim transaction. Claimed runs keep their identity until they finish.
+     */
+    readonly actsAs?: (conn: DatabaseConnection, work: {
+        readonly subjectId: string;
+        readonly agentId: string;
+        readonly causedByRunId?: string;
+        readonly inputs: readonly Pick<RunInput, 'actor' | 'payload'>[];
+    }) => Promise<{
+        readonly actorUserId: string | null;
+        readonly reason?: string;
+    } | undefined>;
+    /**
+     * Reads the current responsible inside the request's transaction, before confirming or rejecting. Null means
+     * nobody answers for it (including a deleted subject). Applications with mutable responsibility must bind this;
+     * without it, requests use their recorded responsible and the application must call `requests.reassign` on changes.
+     */
+    readonly responsibleUserId?: (conn: DatabaseConnection, subjectId: string) => Promise<string | null>;
+    /**
+     * Runs on this kind belong to the people they involve (who woke the agent, the owner): no one else sees them, or
+     * their transcripts and briefs, whatever they may manage (a private conversation).
+     */
+    readonly private?: boolean;
+    /** What a person calls one (`Ticket`); the kind when absent. */
+    readonly title?: I18nText;
+    /** What a person calls the group one belongs to (`SubjectFacts.group`, a `Project`), for the usage page. */
+    readonly groupTitle?: I18nText;
+    /** Where the application shows one and its group, `{id}` standing for the id (`/issues/{id}`), for the usage page. */
+    readonly path?: string;
+    readonly groupPath?: string;
+    /** The reasons a run on it starts (`input.payload.trigger`), as the run panel names them. */
+    readonly triggers?: Readonly<Record<string, I18nText>>;
+    /** Offered as a scenario of "Preview full prompt" on the agent page, rendered on a made-up subject of the kind. */
+    readonly preview?: SubjectSample;
+    readonly context: ContextProvider;
+    readonly sink?: WorkSink;
+    /**
+     * How long a run on this kind may wait in the queue, counted from its last change or from when its delay passed;
+     * past that the sweeper fails it as `queuedExpired`. Without it (or 0), queued runs wait for a runner however long it takes.
+     */
+    readonly queuedExpiryMs?: number;
+    /** Per-run queued withdrawal policy, evaluated under the claim's agent lock by the periodic sweep. Reads only. */
+    readonly queuedTimeout?: (conn: DatabaseConnection, run: Run, now: Date) => Promise<{
+        readonly reason: import('@nocobase/agent-protocol').FailureReason;
+        readonly detail: string;
+    } | null>;
+    /** What the reports may say about the subjects; without it, runs on the kind are reported by id only. */
+    readonly reports?: SubjectReports;
+    /**
+     * Whether the work on a subject is over, so runners may remove the working directories they keep for it. Without
+     * it, no subject of the kind counts as over and runners keep their directories under their own retention rules.
+     */
+    readonly workspaces?: SubjectWorkspaces;
+}
+export interface SubjectRegistry {
+    /** Returns what removes the binding. A kind has one binding. */
+    register(binding: SubjectBinding): () => void;
+    get(kind: string): SubjectBinding | undefined;
+    /** Every binding, in the order they were registered. */
+    list(): SubjectBinding[];
+}
+export declare function createSubjectRegistry(): SubjectRegistry;
+//# sourceMappingURL=ports.d.ts.map

package/dist/server/core/runs/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../../server/core/runs/ports.ts"],"names":[],"mappings":"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"}

package/dist/server/core/runs/ports.js

@@ -0,0 +1,22 @@
+/** A command as a brief names it: `` `acme issue get` ``, with a flag named in `flag` after it (`--file`). */
+export function commandRef(cli, commandId, flag) {
+    const command = `${cli} ${commandId.replaceAll(':', ' ')}`;
+    return flag ? `\`${command} --${flag}\`` : `\`${command}\``;
+}
+export function createSubjectRegistry() {
+    const bindings = new Map();
+    return {
+        register(binding) {
+            if (bindings.has(binding.kind))
+                throw new Error(`Subject kind already registered: ${binding.kind}`);
+            bindings.set(binding.kind, binding);
+            return () => {
+                if (bindings.get(binding.kind) === binding)
+                    bindings.delete(binding.kind);
+            };
+        },
+        get: (kind) => bindings.get(kind),
+        list: () => [...bindings.values()],
+    };
+}
+//# sourceMappingURL=ports.js.map

package/dist/server/core/runs/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../../server/core/runs/ports.ts"],"names":[],"mappings":"AAkBA,8GAA8G;AAC9G,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,SAAiB,EACjB,IAAa;IAEb,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3D,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,CAAC;AAC9D,CAAC;AA2RD,MAAM,UAAU,qBAAqB;IACnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IACnD,OAAO;QACL,QAAQ,CAAC,OAAO;YACd,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YACtE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,GAAG,EAAE;gBACV,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO;oBACxC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAClC,CAAC,CAAC;QACJ,CAAC;QACD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QACjC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;KACnC,CAAC;AACJ,CAAC"}

package/dist/server/core/runs/preview.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Brief previews ("Preview full prompt" on the agent page): what a run of an agent would be sent now in a scenario, a
+ * subject kind that offers a sample (`SubjectBinding.preview`), rendered by the same code a claim uses on a made-up
+ * subject of the kind, stored nowhere and handed to no runner. The run is not real either: it is queued, woken by the
+ * person asking, with the inputs the sample gives (by default, one saying they gave the agent the subject).
+ */
+import type { RunInput } from '@nocobase/agent-protocol';
+import type { BriefPreview } from '../../../shared/briefs.js';
+import type { Clock } from '../../kernel/clock.js';
+import type { TxRunner } from '../../kernel/tx.js';
+import type { SkillService } from '../skills/index.js';
+import { type BriefSectionRegistry } from './extensions.js';
+import { type SubjectRegistry } from './ports.js';
+/** The id a sample subject is previewed under. */
+export declare const SAMPLE_SUBJECT_ID = "sample";
+export interface BriefPreviewer {
+    /** The turn prompt a run is given: what happened since the agent last looked, oldest first. */
+    turnPrompt(inputs: readonly RunInput[], options: {
+        readonly subject: {
+            readonly noun: string;
+            readonly key: string;
+        };
+    }): string;
+    /** The scenario's brief: `scenario` names a subject kind that offers a sample. */
+    preview(agentId: string, scenario: string, user: {
+        readonly id: string;
+        readonly name: string;
+    }): Promise<BriefPreview>;
+    /** Sections the application adds to every brief's context layer, after the subject's own context. */
+    readonly sections: BriefSectionRegistry;
+}
+/**
+ * The system prompt in two: the platform's part, with the runner's placeholders annotated, and the agent's own prompt,
+ * which ends it as written (`joinBrief` puts it last, after a fixed English lead-in that stays with the platform's part).
+ */
+export declare function splitPrompt(prompt: string, instructions: string | null): Pick<BriefPreview, 'platform' | 'agentPrompt'>;
+export declare function createBriefPreviewer(deps: {
+    readonly tx: TxRunner;
+    readonly clock: Clock;
+    readonly subjects: SubjectRegistry;
+    readonly skills: SkillService;
+    readonly cliName: string;
+    /** The application's name in prose (`agents.app.name`). */
+    readonly appName: string;
+    readonly sections: BriefSectionRegistry;
+}): BriefPreviewer;
+//# sourceMappingURL=preview.d.ts.map

package/dist/server/core/runs/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../../server/core/runs/preview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAOnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAGrE,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,+FAA+F;IAC/F,UAAU,CACR,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,OAAO,EAAE;QACP,QAAQ,CAAC,OAAO,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;KACnE,GACA,MAAM,CAAC;IACV,kFAAkF;IAClF,OAAO,CACL,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,aAAa,CAAC,CAQhD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;CACzC,GAAG,cAAc,CAkGjB"}

package/dist/server/core/runs/preview.js

@@ -0,0 +1,104 @@
+import { invalid, notFound } from '../../kernel/errors.js';
+import { findAgent } from '../agents/index.js';
+import { annotatePlaceholders, firstTurn, renderTurnPrompt, } from '../brief/index.js';
+import { briefOf, skillTargets } from './claim.js';
+import { prepareExtensions, withSections, } from './extensions.js';
+import { DEFAULT_THREAD } from './run.service.js';
+/** The id a sample subject is previewed under. */
+export const SAMPLE_SUBJECT_ID = 'sample';
+/**
+ * The system prompt in two: the platform's part, with the runner's placeholders annotated, and the agent's own prompt,
+ * which ends it as written (`joinBrief` puts it last, after a fixed English lead-in that stays with the platform's part).
+ */
+export function splitPrompt(prompt, instructions) {
+    const own = instructions?.trim() ?? '';
+    const at = own && prompt.endsWith(own) ? prompt.length - own.length : prompt.length;
+    return {
+        platform: annotatePlaceholders(prompt.slice(0, at)),
+        agentPrompt: prompt.slice(at),
+    };
+}
+export function createBriefPreviewer(deps) {
+    return {
+        sections: deps.sections,
+        turnPrompt: (inputs, options) => renderTurnPrompt(inputs, { ...options, cli: deps.cliName }),
+        async preview(agentId, scenario, user) {
+            const conn = deps.tx.read();
+            const agent = await findAgent(conn, agentId);
+            if (!agent)
+                throw notFound('Agent');
+            const sample = deps.subjects.get(scenario)?.preview;
+            if (!sample)
+                throw invalid(`Nothing can be previewed for ${scenario}.`, {
+                    field: 'scenario',
+                });
+            const now = deps.clock.now().toISOString();
+            const inputs = sample.inputs?.(user, now) ?? [
+                {
+                    id: 'preview',
+                    type: 'signal',
+                    at: now,
+                    actor: { kind: 'user', id: user.id, name: user.name },
+                    text: `${user.name} gave you this ${scenario} to work on.`,
+                    payload: { trigger: 'assigned' },
+                },
+            ];
+            const claim = {
+                run: {
+                    id: 'preview',
+                    agentId: agent.id,
+                    agentType: 'runner',
+                    runnerId: null,
+                    tool: null,
+                    modelService: null,
+                    model: null,
+                    effort: null,
+                    status: 'queued',
+                    priority: 0,
+                    attempt: 1,
+                    maxAttempts: agent.maxAttempts,
+                    retryOfRunId: null,
+                    parentRunId: null,
+                    subject: { kind: scenario, id: SAMPLE_SUBJECT_ID },
+                    threadScope: DEFAULT_THREAD,
+                    actorUserId: user.id,
+                    requestedByUserId: user.id,
+                    confirmedByUserId: null,
+                    ownerUserId: null,
+                    requires: [],
+                    acceptsInput: false,
+                    availableAt: null,
+                    leaseExpiresAt: null,
+                    dispatchedAt: null,
+                    startedAt: null,
+                    finishedAt: null,
+                    lastActivityAt: null,
+                    cancelRequestedAt: null,
+                    failureReason: null,
+                    failureDetail: null,
+                    summary: null,
+                    createdAt: now,
+                    updatedAt: now,
+                },
+                agent,
+                runner: null,
+                inputs,
+                cli: deps.cliName,
+                appName: deps.appName,
+            };
+            const assembly = await sample.assemble(conn, claim);
+            const skills = await deps.skills.forRun(conn, skillTargets(agent, assembly), 'preview');
+            const brief = briefOf(agent, await withSections(conn, deps.sections, claim, assembly, await prepareExtensions(claim.run, deps.sections, undefined)), skills, deps.cliName, deps.appName);
+            return {
+                scenario,
+                subject: {
+                    key: assembly.subject.key,
+                    title: assembly.subject.title ?? null,
+                },
+                ...splitPrompt(brief.prompt, agent.instructions),
+                firstMessage: firstTurn(brief.turn, inputs),
+            };
+        },
+    };
+}
+//# sourceMappingURL=preview.js.map

package/dist/server/core/runs/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../../server/core/runs/preview.ts"],"names":[],"mappings":"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"}