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

package/dist/shared/agents.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Agents as the browser and the server's admin API exchange them.
+ *
+ * Nobody creates an agent. Each coding tool and model the runners report becomes one agent (`source: 'runner'`): the
+ * runners report, per tool, whether it is installed and signed in and which models it can use, and the server keeps one
+ * agent per tool and model (`model-catalog.ts` names it and normalizes the model), however many runners report it. A new
+ * one waits (`pending`) until someone who manages agents writes what it is good at and enables it. The application may
+ * also keep agents of its own (`source: 'system'`), such as a project manager, which it configures through its own
+ * settings and runs with the tool and model of the agents it names.
+ *
+ * Which tool and model an agent works with, and with what reasoning effort, is an ordered list (`modelEntries`); a
+ * runner takes a run with the first entry it reports. An agent discovered from runners has exactly one entry, its own
+ * tool and model; only its default reasoning effort can be changed. The rest of what an agent is (its instructions,
+ * the business actions it may perform, how many attempts a run gets) is the application's, the same for every agent.
+ */
+import { type AgentTool, type ToolPolicy } from '@nocobase/agent-protocol';
+import type { I18nText } from './i18n.js';
+/** Where an agent comes from: discovered from what runners report, or kept by the application. */
+export declare const AGENT_SOURCES: readonly ["runner", "system"];
+export type AgentSource = (typeof AGENT_SOURCES)[number];
+/**
+ * Whether an agent is offered work: `pending` (discovered, nobody enabled it yet), `enabled`, `disabled`. Only enabled
+ * agents are offered work, mentioned or chatted with.
+ */
+export declare const AGENT_STATUSES: readonly ["pending", "enabled", "disabled"];
+export type AgentStatus = (typeof AGENT_STATUSES)[number];
+/** How long a tool and model may go unreported by every runner before its agent shows as having no runner. */
+export declare const AGENT_UNREPORTED_AFTER_MS: number;
+/** When in a conversation an agent asks before changing data: every change, or only larger ones. */
+export declare const CONFIRM_CHANGES: readonly ["always", "larger"];
+export type ConfirmChanges = (typeof CONFIRM_CHANGES)[number];
+/**
+ * An entry of an agent's list: a coding tool, its model (null: the tool's default) and its reasoning effort, one of the
+ * tool's (`TOOL_EFFORTS`; null or absent: the tool's default).
+ */
+export interface RunnerModelEntry {
+    readonly tool: AgentTool;
+    readonly model: string | null;
+    readonly effort?: string | null;
+}
+/** The most entries an agent's list holds. */
+export declare const MAX_MODEL_ENTRIES = 20;
+/** The reasoning efforts `entry`'s tool takes. */
+export declare function effortsFor(entry: {
+    readonly tool: AgentTool;
+}): readonly string[];
+/** The coding tools an agent's entries name, in order and once each. */
+export declare function entryTools(agent: {
+    readonly modelEntries: readonly RunnerModelEntry[];
+}): AgentTool[];
+/** Whether two entries name the same tool and model, whatever their efforts. */
+export declare function sameEntry(a: RunnerModelEntry, b: RunnerModelEntry): boolean;
+export interface Agent {
+    readonly id: string;
+    /** As the model catalog names it (`Claude · Opus 5.5`), or as the application named its own. */
+    readonly name: string;
+    /** What it is good at: the project manager hands it work by this. Null until someone writes it. */
+    readonly description: string | null;
+    /** An application's own agent's name as an i18n reference, shown in the viewer's language in place of `name`. */
+    readonly nameText: I18nText | null;
+    readonly descriptionText: I18nText | null;
+    /** An image URL; null shows the bot icon. */
+    readonly avatar: string | null;
+    readonly source: AgentSource;
+    readonly status: AgentStatus;
+    /** For an agent discovered from runners: its coding tool and its model, normalized. Null for the application's own. */
+    readonly tool: AgentTool | null;
+    readonly model: string | null;
+    /**
+     * The tools and models it works with, each with its reasoning effort, in order; the first is its default. Exactly one
+     * for an agent discovered from runners; an application's own agent may have none until it is configured.
+     */
+    readonly modelEntries: readonly RunnerModelEntry[];
+    /** The application's built-in instructions, the last layer of the brief. */
+    readonly instructions: string | null;
+    /** Business action keys the agent may perform, within what the person who woke it may do. */
+    readonly actions: readonly string[];
+    /** In conversations: whether it asks before every change or only before larger ones. */
+    readonly confirmChanges: ConfirmChanges;
+    /** The skills attached to the agent, in the skill library. */
+    readonly skillIds: readonly string[];
+    readonly maxConcurrentRuns: number;
+    readonly maxAttempts: number;
+    /** Overrides of the default tool policy (`DEFAULT_TOOL_POLICY`). */
+    readonly toolPolicy: Partial<ToolPolicy> | null;
+    /** When a runner last reported its tool and model; null for the application's own. */
+    readonly lastReportedAt: string | null;
+    /**
+     * Raised by every change (its good-at, its effort, enabling or disabling it). An edit names the revision it was made
+     * against (`AgentPatch.expectedRevision`) and is refused with 409 when the agent changed since.
+     */
+    readonly revision: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/**
+ * Why an agent cannot take the caller's work now: `pending` and `disabled` (not enabled), `unreported` (no runner
+ * reported its tool and model for `AGENT_UNREPORTED_AFTER_MS`), `notConfigured` (an application's own agent with no
+ * tool and model yet), `noRunner` (no runner online that has it and would take the caller's work), `othersPersonal`
+ * (only other people's personal runners have it).
+ */
+export declare const AGENT_UNUSABLE_REASONS: readonly ["pending", "disabled", "unreported", "notConfigured", "noRunner", "othersPersonal"];
+export type AgentUnusableReason = (typeof AGENT_UNUSABLE_REASONS)[number];
+/** Where an agent can run now: the online runners that have its tool and model signed in and take its work. */
+export interface AgentRunners {
+    /** Online team runners: they take anyone's work. */
+    readonly team: number;
+    /** Online personal runners: each takes only its owner's work. */
+    readonly personal: number;
+    /** Of `personal`, the caller's own. */
+    readonly mine: number;
+    /** A few of their names, team runners first. */
+    readonly names: readonly string[];
+}
+/** An agent as the Agent page lists it (`GET /api/agents`), for the caller. */
+export interface AgentView extends Agent {
+    readonly discoveryKey?: string;
+    readonly discoveryRevision?: number;
+    readonly ignored?: boolean;
+    /** Its default reasoning effort: its first entry's. */
+    readonly effort: string | null;
+    /** The efforts its tool takes, weakest first; empty for an application's own agent. */
+    readonly efforts: readonly string[];
+    /** A runner reported its tool and model within `AGENT_UNREPORTED_AFTER_MS`, or it is the application's own. */
+    readonly reported: boolean;
+    readonly runners: AgentRunners;
+    /** Only personal runners have it: it takes the work of their owners only. */
+    readonly personalOnly: boolean;
+    /** Null when it could take the caller's work now; otherwise why not. */
+    readonly unusable: AgentUnusableReason | null;
+    /** Its runs that have not finished. */
+    readonly busy: number;
+    /** What the model catalog says it is good at, to start from when enabling it; null for a model it does not know. */
+    readonly suggestion: {
+        readonly en: string;
+        readonly zh: string;
+    } | null;
+    /** Whether the caller may change it: good-at, effort, enabled. */
+    readonly canEdit: boolean;
+}
+/** An agent's name (`GET /api/agents/agentNames`): every agent there has been, for the runs that name it. */
+export interface AgentName {
+    readonly id: string;
+    readonly name: string;
+    readonly nameText: I18nText | null;
+}
+/** An agent the caller may give work to: what it is good at, and whether it can take work now. */
+export interface AvailableAgent {
+    readonly runners?: AgentRunners;
+    readonly id: string;
+    readonly name: string;
+    /** Its description. */
+    readonly goodAt: string;
+    /** Its coding tool and model. */
+    readonly tool: AgentTool | null;
+    readonly model: string | null;
+    /** Whether it could start the caller's work now: an online runner that has it and would take the work. */
+    readonly online: boolean;
+    /** Only personal runners have it: it takes the work of their owners only. */
+    readonly personalOnly: boolean;
+    /** Its runs that have not finished. */
+    readonly busy: number;
+}
+/**
+ * What changing an agent takes (`PATCH /api/agents/:agentId`): what it is good at, its default reasoning effort and
+ * whether it is enabled, with the revision the edit was made against. An agent is enabled only with a description.
+ */
+export interface AgentPatch {
+    readonly description?: string | null;
+    readonly effort?: string | null;
+    readonly enabled?: boolean;
+    readonly expectedRevision: number;
+}
+/**
+ * What the application keeps of an agent of its own (`AgentService.ensureSystem`): its fixed id, name, description,
+ * instructions, actions and the tools and models it runs with (none until it is configured).
+ */
+export interface SystemAgentInput {
+    readonly id: string;
+    readonly name: string;
+    readonly nameText?: I18nText | null;
+    readonly description: string | null;
+    readonly instructions: string | null;
+    readonly actions: readonly string[];
+    readonly modelEntries: readonly RunnerModelEntry[];
+}
+/** What a change to an agent was. */
+export declare const AGENT_CHANGE_ACTIONS: readonly ["created", "updated", "enabled", "disabled", "variables", "archived", "restored"];
+export type AgentChangeAction = (typeof AGENT_CHANGE_ACTIONS)[number];
+/** The fields of an agent whose changes its history records, in the order the history shows them. */
+export declare const AGENT_HISTORY_FIELDS: readonly ["name", "description", "status", "modelEntries", "instructions", "actions"];
+export type AgentHistoryField = (typeof AGENT_HISTORY_FIELDS)[number];
+/**
+ * One field that changed. A variable is a secret: it is named (`name`) with what happened to it (`change`), never with
+ * its value. Entries recorded by earlier versions may name fields no longer listed here.
+ */
+export type AgentFieldChange = {
+    readonly field: string;
+    readonly before: unknown;
+    readonly after: unknown;
+} | {
+    readonly field: 'variable';
+    readonly name: string;
+    readonly change: 'added' | 'changed' | 'removed';
+};
+/** An entry of an agent's history (`GET /api/agents/:agentId/history`), newest first. */
+export interface AgentChange {
+    readonly id: string;
+    readonly agentId: string;
+    /** The agent's revision after the change. */
+    readonly revision: number;
+    readonly action: AgentChangeAction;
+    readonly actorUserId: string | null;
+    readonly actorName: string | null;
+    readonly changes: readonly AgentFieldChange[];
+    readonly createdAt: string;
+}
+/**
+ * A business action the application lets agents perform (`GET /api/agents/actions`): the key its commands name, and
+ * how it is shown.
+ */
+export interface AgentActionOption {
+    /** The business action key the server stores, such as `crm.deals/comment`. */
+    readonly key: string;
+    /** What groups it, such as `crm.deals`. */
+    readonly group: string;
+    /** The label; the key when absent. */
+    readonly title?: I18nText;
+    /** The group's heading; the group when absent. */
+    readonly groupTitle?: I18nText;
+    /** One line saying what it lets the agent do. */
+    readonly description?: I18nText;
+    /** Given to every agent the runners report. */
+    readonly defaultOn?: boolean;
+    /** False for an action listed only to show where the boundary is: it is never granted. Grantable when absent. */
+    readonly grantable?: boolean;
+    /** Why it can never be granted to an agent, for a `grantable: false` action. */
+    readonly reason?: I18nText;
+}
+/** A person, as pickers and audit lines show them (`GET /api/agents/users`). */
+export interface UserRef {
+    readonly id: string;
+    readonly name: string;
+}
+/** The tool policy every agent runs with; an agent's `toolPolicy` overrides fields of it. */
+export declare const DEFAULT_TOOL_POLICY: ToolPolicy;
+//# sourceMappingURL=agents.d.ts.map

package/dist/shared/agents.d.ts.map

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

package/dist/shared/agents.js

@@ -0,0 +1,92 @@
+/**
+ * Agents as the browser and the server's admin API exchange them.
+ *
+ * Nobody creates an agent. Each coding tool and model the runners report becomes one agent (`source: 'runner'`): the
+ * runners report, per tool, whether it is installed and signed in and which models it can use, and the server keeps one
+ * agent per tool and model (`model-catalog.ts` names it and normalizes the model), however many runners report it. A new
+ * one waits (`pending`) until someone who manages agents writes what it is good at and enables it. The application may
+ * also keep agents of its own (`source: 'system'`), such as a project manager, which it configures through its own
+ * settings and runs with the tool and model of the agents it names.
+ *
+ * Which tool and model an agent works with, and with what reasoning effort, is an ordered list (`modelEntries`); a
+ * runner takes a run with the first entry it reports. An agent discovered from runners has exactly one entry, its own
+ * tool and model; only its default reasoning effort can be changed. The rest of what an agent is (its instructions,
+ * the business actions it may perform, how many attempts a run gets) is the application's, the same for every agent.
+ */
+import { TOOL_EFFORTS, } from '@nocobase/agent-protocol';
+/** Where an agent comes from: discovered from what runners report, or kept by the application. */
+export const AGENT_SOURCES = ['runner', 'system'];
+/**
+ * Whether an agent is offered work: `pending` (discovered, nobody enabled it yet), `enabled`, `disabled`. Only enabled
+ * agents are offered work, mentioned or chatted with.
+ */
+export const AGENT_STATUSES = ['pending', 'enabled', 'disabled'];
+/** How long a tool and model may go unreported by every runner before its agent shows as having no runner. */
+export const AGENT_UNREPORTED_AFTER_MS = 14 * 24 * 60 * 60_000;
+/** When in a conversation an agent asks before changing data: every change, or only larger ones. */
+export const CONFIRM_CHANGES = ['always', 'larger'];
+/** The most entries an agent's list holds. */
+export const MAX_MODEL_ENTRIES = 20;
+/** The reasoning efforts `entry`'s tool takes. */
+export function effortsFor(entry) {
+    return TOOL_EFFORTS[entry.tool];
+}
+/** The coding tools an agent's entries name, in order and once each. */
+export function entryTools(agent) {
+    return [...new Set(agent.modelEntries.map((entry) => entry.tool))];
+}
+/** Whether two entries name the same tool and model, whatever their efforts. */
+export function sameEntry(a, b) {
+    return a.tool === b.tool && (a.model ?? null) === (b.model ?? null);
+}
+/**
+ * Why an agent cannot take the caller's work now: `pending` and `disabled` (not enabled), `unreported` (no runner
+ * reported its tool and model for `AGENT_UNREPORTED_AFTER_MS`), `notConfigured` (an application's own agent with no
+ * tool and model yet), `noRunner` (no runner online that has it and would take the caller's work), `othersPersonal`
+ * (only other people's personal runners have it).
+ */
+export const AGENT_UNUSABLE_REASONS = [
+    'pending',
+    'disabled',
+    'unreported',
+    'notConfigured',
+    'noRunner',
+    'othersPersonal',
+];
+/** What a change to an agent was. */
+export const AGENT_CHANGE_ACTIONS = [
+    'created',
+    'updated',
+    'enabled',
+    'disabled',
+    'variables',
+    // Recorded by earlier versions, which kept agents people configured.
+    'archived',
+    'restored',
+];
+/** The fields of an agent whose changes its history records, in the order the history shows them. */
+export const AGENT_HISTORY_FIELDS = [
+    'name',
+    'description',
+    'status',
+    'modelEntries',
+    'instructions',
+    'actions',
+];
+/** The tool policy every agent runs with; an agent's `toolPolicy` overrides fields of it. */
+export const DEFAULT_TOOL_POLICY = {
+    permissionMode: 'acceptEdits',
+    allowedCommands: [
+        '^(cd|git|ls|cat|head|tail|grep|rg|find|wc|diff|sed|awk|sort|uniq|echo|printf|pwd|which|mkdir|touch|cp|mv)\\b',
+        '^(node|npm|npx|pnpm|yarn|tsc|vitest|jest|eslint|prettier|python3?|pip3?|pytest|go|cargo|make)\\b',
+    ],
+    deniedPatterns: [
+        '\\brm\\s+-[a-z]*r[a-z]*f?\\s+/(\\s|$)',
+        '\\bsudo\\b',
+        '\\bcurl\\b[^|]*\\|\\s*(sh|bash|zsh)\\b',
+        '\\bgit\\s+push\\b[^\\n]*--force\\b',
+        '\\bchmod\\s+-R\\s+777\\b',
+    ],
+    idleTimeoutMs: 30 * 60_000,
+};
+//# sourceMappingURL=agents.js.map

package/dist/shared/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../shared/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,YAAY,GAGb,MAAM,0BAA0B,CAAC;AAIlC,kGAAkG;AAClG,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAI3D;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAI1E,8GAA8G;AAC9G,MAAM,CAAC,MAAM,yBAAyB,GAAW,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAEvE,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAc7D,8CAA8C;AAC9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,KAE1B;IACC,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,KAE1B;IACC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,CAAmB,EAAE,CAAmB;IAChE,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;AACtE,CAAC;AA8CD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS;IACT,UAAU;IACV,YAAY;IACZ,eAAe;IACf,UAAU;IACV,gBAAgB;CACR,CAAC;AA0FX,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS;IACT,SAAS;IACT,SAAS;IACT,UAAU;IACV,WAAW;IACX,qEAAqE;IACrE,UAAU;IACV,UAAU;CACF,CAAC;AAIX,qGAAqG;AACrG,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,MAAM;IACN,aAAa;IACb,QAAQ;IACR,cAAc;IACd,cAAc;IACd,SAAS;CACD,CAAC;AA8DX,6FAA6F;AAC7F,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,cAAc,EAAE,aAAa;IAC7B,eAAe,EAAE;QACf,8GAA8G;QAC9G,kGAAkG;KACnG;IACD,cAAc,EAAE;QACd,uCAAuC;QACvC,YAAY;QACZ,wCAAwC;QACxC,oCAAoC;QACpC,0BAA0B;KAC3B;IACD,aAAa,EAAE,EAAE,GAAG,MAAM;CAC3B,CAAC"}

package/dist/shared/briefs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The brief an agent runs with, as people read it: the four layers the server renders (rules, task, context, the
+ * agent's own instructions) and the first turn. The runner adds what only it knows where the system prompt holds its
+ * placeholders (`{{runner.workspaceNotes}}`, `{{runner.workspaceInit}}`).
+ */
+export interface BriefLayers {
+    readonly system: string;
+    readonly task: string;
+    readonly context: string;
+    readonly agent: string;
+}
+/** A made-up value in a previewed brief, marked so nobody mistakes it for data. */
+export declare function sampleValue(text: string): string;
+/**
+ * `GET /api/agents/:agentId/previewBrief?scenario=`: what a run of the agent on a made-up subject of the scenario's kind
+ * would be sent now (`SubjectSample`), the made-up values marked with `sampleValue`.
+ */
+export interface BriefPreview {
+    /** The subject kind the brief was rendered for (for example, `issue` or `conversation`). */
+    readonly scenario: string;
+    /** The made-up subject. */
+    readonly subject: {
+        readonly key: string;
+        readonly title: string | null;
+    };
+    /**
+     * The system prompt as the runner or the online executor receives it is `platform` followed by `agentPrompt`.
+     * `platform` is everything before the agent's own prompt: the rules, the task, the context and the English lead-in to
+     * the agent's prompt. The runner's placeholders are shown annotated.
+     */
+    readonly platform: string;
+    /** The agent's own prompt as written, which ends the system prompt; empty when the agent has none. */
+    readonly agentPrompt: string;
+    /** The first message: the turn the agent is given, with what woke it. */
+    readonly firstMessage: string;
+}
+/** `GET /api/agents/runs/:runId/brief`: the brief the run's latest attempt was given. */
+export interface RunBrief {
+    readonly runId: string;
+    readonly attempt: number;
+    readonly layers: BriefLayers;
+    readonly turn: string;
+    readonly prompt: string;
+    readonly createdAt: string;
+}
+//# sourceMappingURL=briefs.d.ts.map

package/dist/shared/briefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefs.d.ts","sourceRoot":"","sources":["../../shared/briefs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC1E;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sGAAsG;IACtG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/shared/briefs.js

@@ -0,0 +1,10 @@
+/**
+ * The brief an agent runs with, as people read it: the four layers the server renders (rules, task, context, the
+ * agent's own instructions) and the first turn. The runner adds what only it knows where the system prompt holds its
+ * placeholders (`{{runner.workspaceNotes}}`, `{{runner.workspaceInit}}`).
+ */
+/** A made-up value in a previewed brief, marked so nobody mistakes it for data. */
+export function sampleValue(text) {
+    return `[sample] ${text}`;
+}
+//# sourceMappingURL=briefs.js.map

package/dist/shared/briefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefs.js","sourceRoot":"","sources":["../../shared/briefs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,YAAY,IAAI,EAAE,CAAC;AAC5B,CAAC"}