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

package/dist/server/core/agents/agent.history.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The history of an agent's configuration (`agAgentChanges`): who changed what and when, a field at a time. Only this
+ * file reads or writes it. A variable is a secret, so its entry names it and says whether it was added, changed or
+ * removed, never what it holds.
+ */
+import type { DatabaseConnection } from '@nocobase/db';
+import { type Agent, type AgentChange, type AgentChangeAction, type AgentFieldChange } from '../../../shared/agents.js';
+import type { People } from '../../kernel/people.js';
+/** The fields that differ between two states of an agent, in the order the history shows them. */
+export declare function diffAgents(before: Agent, after: Agent): AgentFieldChange[];
+export declare function recordChange(conn: DatabaseConnection, entry: {
+    readonly id: string;
+    readonly agentId: string;
+    readonly revision: number;
+    readonly action: AgentChangeAction;
+    readonly actorUserId: string | null;
+    readonly changes: readonly AgentFieldChange[];
+    readonly createdAt: string;
+}): Promise<void>;
+/** The agent's history, newest first; with `afterRevision`, only the changes that came after it. */
+/** Which changes to read: after a revision, and a page at a time (`cursor`: the last change of the previous page). */
+export interface HistoryOptions {
+    readonly afterRevision?: number;
+    readonly limit?: number;
+    readonly cursor?: {
+        readonly createdAt: string;
+        readonly revision: number;
+        readonly id: string;
+    };
+}
+export declare function listChanges(conn: DatabaseConnection, people: People, agentId: string, options?: HistoryOptions): Promise<AgentChange[]>;
+//# sourceMappingURL=agent.history.d.ts.map

package/dist/server/core/agents/agent.history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.history.d.ts","sourceRoot":"","sources":["../../../../server/core/agents/agent.history.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,cAAc,CAAC;AAEnE,OAAO,EAGL,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAmCrD,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,gBAAgB,EAAE,CAQ1E;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE;IACL,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACA,OAAO,CAAC,IAAI,CAAC,CAIf;AAOD,oGAAoG;AACpG,sHAAsH;AACtH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAsCxB"}

package/dist/server/core/agents/agent.history.js

@@ -0,0 +1,71 @@
+import { AGENT_CHANGE_ACTIONS, AGENT_HISTORY_FIELDS, } from '../../../shared/agents.js';
+import { asJson } from '../../kernel/values.js';
+const CHANGES = 'agAgentChanges';
+function changesRepo(conn) {
+    return conn.repository(CHANGES);
+}
+/** Lists of strings compare as sets, everything else (the ordered model entries too) as JSON. */
+function same(before, after) {
+    if (Array.isArray(before) &&
+        Array.isArray(after) &&
+        before
+            .concat(after)
+            .every((item) => typeof item === 'string'))
+        return (before.length === after.length &&
+            before.every((item) => after.includes(item)));
+    return JSON.stringify(before ?? null) === JSON.stringify(after ?? null);
+}
+/** The fields that differ between two states of an agent, in the order the history shows them. */
+export function diffAgents(before, after) {
+    const changes = [];
+    for (const field of AGENT_HISTORY_FIELDS) {
+        const from = before[field] ?? null;
+        const to = after[field] ?? null;
+        if (!same(from, to))
+            changes.push({ field, before: from, after: to });
+    }
+    return changes;
+}
+export async function recordChange(conn, entry) {
+    await changesRepo(conn).createOne({
+        values: { ...entry, changes: asJson(entry.changes) },
+    });
+}
+function changesOf(value) {
+    const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+    return Array.isArray(parsed) ? parsed : [];
+}
+export async function listChanges(conn, people, agentId, options = {}) {
+    const { afterRevision } = options;
+    const records = await changesRepo(conn).findMany({
+        filter: (f) => f.and([
+            f.string('agentId').eq(agentId),
+            ...(afterRevision === undefined
+                ? []
+                : [f.number('revision').gt(afterRevision)]),
+        ]),
+        sort: (sort) => [
+            sort.field('createdAt').desc(),
+            sort.field('revision').desc(),
+            sort.field('id').desc(),
+        ],
+        limit: options.limit ?? 200,
+        ...(options.cursor ? { cursor: options.cursor } : {}),
+    });
+    const names = await people.names(conn, records.flatMap((record) => record.actorUserId ? [record.actorUserId] : []));
+    return records.map((record) => ({
+        id: record.id,
+        agentId: record.agentId,
+        revision: Number(record.revision),
+        action: AGENT_CHANGE_ACTIONS.includes(record.action)
+            ? record.action
+            : 'updated',
+        actorUserId: record.actorUserId,
+        actorName: record.actorUserId
+            ? (names.get(record.actorUserId) ?? null)
+            : null,
+        changes: changesOf(record.changes),
+        createdAt: record.createdAt,
+    }));
+}
+//# sourceMappingURL=agent.history.js.map

package/dist/server/core/agents/agent.history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.history.js","sourceRoot":"","sources":["../../../../server/core/agents/agent.history.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAKrB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,MAAM,EAAmB,MAAM,wBAAwB,CAAC;AAEjE,MAAM,OAAO,GAAG,gBAAgB,CAAC;AAYjC,SAAS,WAAW,CAAC,IAAwB;IAC3C,OAAO,IAAI,CAAC,UAAU,CAAe,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,iGAAiG;AACjG,SAAS,IAAI,CAAC,MAAe,EAAE,KAAc;IAC3C,IACE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACrB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACnB,MAAoB;aAClB,MAAM,CAAC,KAAkB,CAAC;aAC1B,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC;QAE5C,OAAO,CACL,MAAM,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;YAC9B,MAAM,CAAC,KAAK,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CACtD,CAAC;IACJ,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,MAAa,EAAE,KAAY;IACpD,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,oBAAoB,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;QACnC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAwB,EACxB,KAQC;IAED,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC;QAChC,MAAM,EAAE,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE;KACrD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,SAAS,CAAC,KAAiB;IAClC,MAAM,MAAM,GAAY,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9E,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;AACrE,CAAC;AAcD,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB,EACxB,MAAc,EACd,OAAe,EACf,UAA0B,EAAE;IAE5B,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;QAC/C,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CACZ,CAAC,CAAC,GAAG,CAAC;YACJ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC;YAC/B,GAAG,CAAC,aAAa,KAAK,SAAS;gBAC7B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;SAC9C,CAAC;QACJ,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;YACd,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE;YAC9B,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE;YAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;SACxB;QACD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG;QAC3B,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAC9B,IAAI,EACJ,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CACzB,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAC/C,CACF,CAAC;IACF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC9B,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,EAAG,oBAA0C,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;YACzE,CAAC,CAAE,MAAM,CAAC,MAA4B;YACtC,CAAC,CAAC,SAAS;QACb,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,SAAS,EAAE,MAAM,CAAC,WAAW;YAC3B,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;YACzC,CAAC,CAAC,IAAI;QACR,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC;QAClC,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/server/core/agents/agent.service.d.ts

@@ -0,0 +1,85 @@
+import type { DatabaseConnection } from '@nocobase/db';
+import { z } from 'zod';
+import { type Agent, type AgentChange, type AgentInput, type AgentModelEntry, type AgentPatch, type AgentType } from '../../../shared/agents.js';
+import type { I18nText } from '../../../shared/i18n.js';
+import { type ModelCatalog } from '../../../shared/models.js';
+import type { Clock } from '../../kernel/clock.js';
+import type { IdSource } from '../../kernel/ids.js';
+import type { People } from '../../kernel/people.js';
+import type { Tx, TxRunner } from '../../kernel/tx.js';
+import { type HistoryOptions } from './agent.history.js';
+/**
+ * An agent's list of tools and models: runner entries (`{ tool, model?, effort? }`) or online ones
+ * (`{ modelService, model, effort? }`).
+ */
+export declare const ModelEntriesSchema: z.ZodType<AgentModelEntry[]>;
+/** What creating an agent accepts. */
+export declare const AgentInputSchema: z.ZodType<AgentInput>;
+/**
+ * What updating an agent accepts: any field of the input but its type, and the revision the edit was made against. A
+ * patch naming a type is refused (`AGENT_TYPE_IMMUTABLE`) rather than having it ignored.
+ */
+export declare const AgentPatchSchema: z.ZodType<AgentPatch>;
+export interface AgentService {
+    list(options?: {
+        readonly includeArchived?: boolean;
+    }): Promise<Agent[]>;
+    /** 404 when absent. */
+    get(id: string): Promise<Agent>;
+    find(conn: DatabaseConnection, id: string): Promise<Agent | null>;
+    /** The agent when it can be given work (present and not archived), read on `conn`. */
+    findWorkable(conn: DatabaseConnection, id: string): Promise<Agent | null>;
+    /** The agents not archived, by name, read on `conn`. */
+    listActive(conn: DatabaseConnection): Promise<Agent[]>;
+    create(createdById: string, input: AgentCreation): Promise<Agent>;
+    /**
+     * Changes the fields `patch` names, as `byUserId`, when the agent is still at `patch.expectedRevision`: 409
+     * `REVISION_CONFLICT` with the current `metadata.revision` otherwise. A patch that changes
+     * nothing leaves the revision and the history alone.
+     */
+    update(id: string, byUserId: string | null, patch: AgentPatch): Promise<Agent>;
+    /**
+     * Archived agents are not run: their queued runs are withdrawn now, and `agent.removed` is announced so the
+     * application lets go of the work it gave the agent.
+     */
+    archive(id: string, byUserId: string | null): Promise<Agent>;
+    restore(id: string, byUserId: string | null): Promise<Agent>;
+    /**
+     * Deletes an archived agent with no open runs, its variables, skill attachments and history; its past runs stay.
+     * `CONFLICT` otherwise. Announces `agent.removed`.
+     */
+    remove(id: string, byUserId: string | null): Promise<void>;
+    /** The agent's history, newest first; with `afterRevision`, the changes made after that revision. 404 when absent. */
+    history(id: string, options?: HistoryOptions): Promise<AgentChange[]>;
+    /** Records in the agent's history, on `conn`, that one of its variables was added, changed or removed. */
+    noteVariable(conn: DatabaseConnection, agentId: string, variable: {
+        readonly name: string;
+        readonly change: 'added' | 'changed' | 'removed';
+        readonly byUserId: string | null;
+    }): Promise<void>;
+    /** Whether `userId` may wake the agent. */
+    mayInvoke(agent: Agent, userId: string): boolean;
+}
+export interface AgentServiceDeps {
+    readonly tx: TxRunner;
+    readonly ids: IdSource;
+    readonly clock: Clock;
+    /** Names of the people in the history. */
+    readonly people: People;
+    /** The models online agents may use (the model gateway's catalog): one is saved only with a model offered now. */
+    readonly models: () => Promise<ModelCatalog>;
+    /** The agent types a business action may be given to (`AgentActionOption.types`); every type when undefined. */
+    readonly actionTypes?: (key: string) => readonly AgentType[] | undefined;
+    /** The agent's variables and runs: deleting it checks its open runs and clears its variables; archiving it withdraws its queued runs. */
+    readonly owned?: {
+        readonly openRuns: (conn: DatabaseConnection, agentId: string) => Promise<number>;
+        readonly clearVariables: (conn: DatabaseConnection, agentId: string) => Promise<void>;
+        readonly withdrawQueued: (unit: Tx, agentId: string, byUserId: string | null) => Promise<void>;
+    };
+}
+/** What creating an agent takes inside the server: the input, and a description's i18n reference a copy keeps. */
+export type AgentCreation = AgentInput & {
+    readonly descriptionText?: I18nText | null;
+};
+export declare function createAgentService(deps: AgentServiceDeps): AgentService;
+//# sourceMappingURL=agent.service.d.ts.map

package/dist/server/core/agents/agent.service.d.ts.map

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

package/dist/server/core/agents/agent.service.js

@@ -0,0 +1,427 @@
+/**
+ * Agents: who they are, their type, which tool or model they work with and how, their skills, which runners may run
+ * them and who may wake them. An agent's type is chosen when it is created and never changes: a `runner` agent drives a
+ * coding tool on a runner, an `online` agent talks to a model of a model service on the server and has no tool, runners,
+ * tool policy or variables (`checkType`); its skills are read in a sandbox, their scripts never run.
+ * Who may change an agent is the route's concern (the `agents.agents` settings item, or the `agents.config` `edit`
+ * action's level); the service checks the values and the revision an edit was made against, and keeps the history of
+ * every change (`agent.history.ts`).
+ *
+ * Archiving or deleting an agent withdraws its queued runs and announces `agent.removed`, so the application lets go
+ * of the work it gave the agent (the assembling application clears it as executor of unfinished issues).
+ */
+import { AgentToolSchema, PERMISSION_MODES } from '@nocobase/agent-protocol';
+import { z } from 'zod';
+import { AGENT_ACCESS, CONFIRM_CHANGES, AGENT_TYPES, effortsFor, isOnlineEntry, isRunnerEntry, MAX_MODEL_ENTRIES, sameEntry, } from '../../../shared/agents.js';
+import { offers } from '../../../shared/models.js';
+import { invalid, notFound, precondition, ProtocolError, } from '../../kernel/errors.js';
+import { cleanList } from '../../kernel/values.js';
+import { attachmentsRepo, replaceAttachments, skillsRepo, } from '../skills/skill.store.js';
+import { diffAgents, listChanges, recordChange, } from './agent.history.js';
+import { deleteAgent, findAgent, insertAgent, listAgents, replaceUsers, reviseAgent, } from './agent.store.js';
+const ToolPolicyPatchSchema = z
+    .object({
+    permissionMode: z.enum(PERMISSION_MODES),
+    allowedCommands: z.array(z.string().max(500)).max(200),
+    deniedPatterns: z.array(z.string().max(500)).max(200),
+    allowedDownloads: z.array(z.string().max(500)).max(200),
+    maxTurns: z.number().int().positive(),
+    idleTimeoutMs: z.number().int().min(60_000).max(86_400_000),
+})
+    .partial();
+/** An entry's reasoning effort; empty for the default. Which values its tool or service takes is `checkType`'s. */
+const EffortSchema = z
+    .string()
+    .trim()
+    .max(32)
+    .nullable()
+    .optional()
+    .transform((effort) => (effort ? effort : null));
+const RunnerEntrySchema = z.strictObject({
+    tool: AgentToolSchema,
+    model: z
+        .string()
+        .trim()
+        .max(200)
+        .nullable()
+        .optional()
+        .transform((model) => (model ? model : null)),
+    effort: EffortSchema,
+});
+const OnlineEntrySchema = z.strictObject({
+    modelService: z.string().trim().min(1).max(100),
+    model: z.string().trim().min(1).max(200),
+    effort: EffortSchema,
+});
+/**
+ * An agent's list of tools and models: runner entries (`{ tool, model?, effort? }`) or online ones
+ * (`{ modelService, model, effort? }`).
+ */
+export const ModelEntriesSchema = z
+    .array(z.union([RunnerEntrySchema, OnlineEntrySchema]))
+    .max(MAX_MODEL_ENTRIES)
+    .meta({
+    description: 'The tools and models, in order, the first its default, each with an optional reasoning effort its tool or service takes: `[{"tool":"codex","model":"gpt-5","effort":"high"},{"tool":"claude"}]` for a runner agent, `[{"modelService":"openai","model":"gpt-5","effort":"low"}]` for an online one. A runner agent needs at least one; an online agent may have none until a model is configured.',
+});
+const fields = {
+    name: z.string().trim().min(1).max(200),
+    description: z.string().max(10_000).nullable(),
+    avatar: z.string().trim().max(500).nullable(),
+    modelEntries: ModelEntriesSchema,
+    instructions: z.string().max(100_000).nullable(),
+    runnerIds: z.array(z.string().min(1).max(64)).max(100),
+    skillIds: z.array(z.string().min(1).max(64)).max(100),
+    actions: z.array(z.string().min(1).max(100)).max(100),
+    confirmChanges: z.enum(CONFIRM_CHANGES),
+    access: z.enum(AGENT_ACCESS),
+    userIds: z.array(z.string().min(1).max(64)).max(500),
+    ownerUserId: z.string().min(1).max(64),
+    maxConcurrentRuns: z.number().int().min(1).max(100),
+    maxAttempts: z.number().int().min(1).max(10),
+    toolPolicy: ToolPolicyPatchSchema.nullable(),
+};
+/** What creating an agent accepts. */
+export const AgentInputSchema = z.strictObject({
+    ...fields,
+    type: z.enum(AGENT_TYPES).optional(),
+    modelEntries: fields.modelEntries.optional(),
+    description: fields.description.optional(),
+    avatar: fields.avatar.optional(),
+    instructions: fields.instructions.optional(),
+    runnerIds: fields.runnerIds.optional(),
+    skillIds: fields.skillIds.optional(),
+    actions: fields.actions.optional(),
+    confirmChanges: fields.confirmChanges.optional(),
+    access: fields.access.optional(),
+    userIds: fields.userIds.optional(),
+    ownerUserId: fields.ownerUserId.optional(),
+    maxConcurrentRuns: fields.maxConcurrentRuns.optional(),
+    maxAttempts: fields.maxAttempts.optional(),
+    toolPolicy: fields.toolPolicy.optional(),
+});
+/**
+ * What updating an agent accepts: any field of the input but its type, and the revision the edit was made against. A
+ * patch naming a type is refused (`AGENT_TYPE_IMMUTABLE`) rather than having it ignored.
+ */
+export const AgentPatchSchema = z
+    .strictObject(fields)
+    .partial()
+    .extend({
+    expectedRevision: z.number().int().min(1),
+    type: z.never({ error: 'An agent keeps its type.' }).optional(),
+});
+/** Thrown inside an update's transaction when the patch changes nothing, to roll the raised revision back. */
+class Unchanged extends Error {
+    agent;
+    constructor(agent) {
+        super('unchanged');
+        this.agent = agent;
+    }
+}
+function revisionConflict(current) {
+    return new ProtocolError('REVISION_CONFLICT', 'The agent was changed by someone else since you opened it. Reload it to see what changed, then make your change again.', { revision: current });
+}
+function columns(input) {
+    const values = {};
+    for (const key of [
+        'name',
+        'description',
+        'avatar',
+        'modelEntries',
+        'instructions',
+        'confirmChanges',
+        'access',
+        'ownerUserId',
+        'maxConcurrentRuns',
+        'maxAttempts',
+        'toolPolicy',
+    ])
+        if (input[key] !== undefined)
+            values[key] = input[key];
+    if (input.runnerIds !== undefined)
+        values.runnerIds = cleanList(input.runnerIds);
+    if (input.actions !== undefined)
+        values.actions = cleanList(input.actions);
+    return values;
+}
+/** Attaches `skillIds` to the agent; unknown skills are refused. */
+async function attachSkills(conn, agentId, skillIds, ids, now) {
+    const unique = cleanList(skillIds);
+    if (unique.length > 0) {
+        const found = await skillsRepo(conn).findMany({
+            filter: (f) => f.or(unique.map((id) => f.string('id').eq(id))),
+        });
+        if (found.length !== unique.length)
+            throw invalid('Some of the skills do not exist.');
+    }
+    await replaceAttachments(conn, 'agent', agentId, unique, () => ids.next(), now);
+}
+/**
+ * 400 unless the fields fit the type: a runner agent's entries name coding tools, at least one; an online agent's name
+ * model services and their models (none while it is not configured), and it has none of what only a runner uses
+ * (runners, a tool policy), nor a business action meant for runner agents only. No entry is listed twice, and each
+ * entry's effort is one its tool or service takes.
+ */
+async function checkType(deps, agent, 
+/** The entries saved before; an online entry among them stays even when its service no longer offers it. */
+previous) {
+    const wrongType = (key) => (deps.actionTypes?.(key) ?? AGENT_TYPES).includes(agent.type) === false;
+    const refused = agent.actions.filter(wrongType);
+    if (refused.length > 0)
+        throw invalid(`A ${agent.type} agent cannot be given ${refused.join(', ')}.`, { reason: 'ACTION_NOT_FOR_TYPE', actions: refused });
+    const entries = agent.modelEntries;
+    if (entries.length === 0 && agent.type === 'runner')
+        throw invalid('A runner agent needs at least one coding tool (modelEntries).');
+    if (entries.some((entry, index) => entries.slice(0, index).some((other) => sameEntry(entry, other))))
+        throw invalid('The same tool and model are listed twice.');
+    for (const entry of entries)
+        if (entry.effort && !effortsFor(entry).includes(entry.effort))
+            throw invalid(`${isRunnerEntry(entry) ? entry.tool : entry.modelService} takes no reasoning effort ${entry.effort}: use one of ${effortsFor(entry).join(', ')}.`, { reason: 'EFFORT_UNSUPPORTED' });
+    if (agent.type === 'runner') {
+        if (!entries.every(isRunnerEntry))
+            throw invalid('A runner agent works with coding tools: each entry names a tool, not a model service.');
+        return;
+    }
+    if (!entries.every(isOnlineEntry))
+        throw invalid('An online agent has no coding tool: each entry names a model service and a model.');
+    if (agent.runnerIds.length > 0 || agent.toolPolicy !== null)
+        throw invalid('An online agent runs on the server: it takes no runners or tool policy.');
+    // An entry saved before its service changed stays until someone changes it; a new one must be offered now.
+    const added = entries.filter((entry) => !previous.some((saved) => sameEntry(saved, entry)));
+    if (added.length === 0)
+        return;
+    const catalog = await deps.models();
+    for (const entry of added)
+        if (!offers(catalog, entry.modelService, entry.model))
+            throw invalid(`The model service ${entry.modelService} does not offer the model ${entry.model}.`, { reason: 'MODEL_UNAVAILABLE' });
+}
+export function createAgentService(deps) {
+    const { tx, ids, clock, people } = deps;
+    const require = async (conn, id) => {
+        const agent = await findAgent(conn, id);
+        if (!agent)
+            throw notFound('Agent');
+        return agent;
+    };
+    /** Raises the revision from `agent.revision` with `values`, or refuses when someone got there first. */
+    const revise = async (conn, agent, values) => {
+        if (!(await reviseAgent(conn, agent.id, agent.revision, values)))
+            throw revisionConflict((await require(conn, agent.id)).revision);
+    };
+    const removed = (unit, agent, reason, byUserId) => unit.emit({
+        type: 'agent.removed',
+        agentId: agent.id,
+        name: agent.name,
+        reason,
+        byUserId,
+    });
+    return {
+        list: (options = {}) => listAgents(tx.read(), options.includeArchived ?? false),
+        get: (id) => require(tx.read(), id),
+        find: findAgent,
+        async findWorkable(conn, id) {
+            const agent = await findAgent(conn, id);
+            if (!agent || agent.archivedAt)
+                return null;
+            return agent;
+        },
+        listActive: (conn) => listAgents(conn, false),
+        async create(createdById, input) {
+            const type = input.type ?? 'runner';
+            await checkType(deps, {
+                type,
+                modelEntries: input.modelEntries ?? [],
+                runnerIds: input.runnerIds ?? [],
+                toolPolicy: input.toolPolicy ?? null,
+                skillIds: input.skillIds ?? [],
+                actions: input.actions ?? [],
+            }, []);
+            return tx.run(async ({ conn, emit }) => {
+                const now = clock.now().toISOString();
+                const id = ids.next();
+                await insertAgent(conn, {
+                    id,
+                    name: input.name,
+                    description: input.description ?? null,
+                    nameText: null,
+                    descriptionText: input.descriptionText
+                        ? { ...input.descriptionText }
+                        : null,
+                    avatar: input.avatar ?? null,
+                    type,
+                    modelEntries: [...(input.modelEntries ?? [])],
+                    instructions: input.instructions ?? null,
+                    runnerIds: cleanList(input.runnerIds ?? []),
+                    actions: cleanList(input.actions ?? []),
+                    confirmChanges: input.confirmChanges ?? 'larger',
+                    access: input.access ?? 'ownerOnly',
+                    ownerUserId: input.ownerUserId ?? createdById,
+                    maxConcurrentRuns: input.maxConcurrentRuns ?? 2,
+                    maxAttempts: input.maxAttempts ?? 3,
+                    toolPolicy: input.toolPolicy ?? null,
+                    createdAt: now,
+                    updatedAt: now,
+                });
+                await replaceUsers(conn, id, cleanList(input.userIds ?? []), () => ids.next(), now);
+                if (input.skillIds !== undefined)
+                    await attachSkills(conn, id, input.skillIds, ids, now);
+                await recordChange(conn, {
+                    id: ids.next(),
+                    agentId: id,
+                    revision: 1,
+                    action: 'created',
+                    actorUserId: createdById,
+                    changes: [],
+                    createdAt: now,
+                });
+                emit({ type: 'agent.changed', agentId: id });
+                return require(conn, id);
+            });
+        },
+        async update(id, byUserId, patch) {
+            const current = await require(tx.read(), id);
+            await checkType(deps, {
+                type: current.type,
+                modelEntries: patch.modelEntries ?? current.modelEntries,
+                runnerIds: patch.runnerIds ?? current.runnerIds,
+                toolPolicy: patch.toolPolicy === undefined
+                    ? current.toolPolicy
+                    : patch.toolPolicy,
+                skillIds: patch.skillIds ?? current.skillIds,
+                actions: patch.actions ?? current.actions,
+            }, current.modelEntries);
+            try {
+                return await tx.run(async ({ conn, emit }) => {
+                    const before = await require(conn, id);
+                    if (patch.expectedRevision !== before.revision)
+                        throw revisionConflict(before.revision);
+                    const now = clock.now().toISOString();
+                    await revise(conn, before, {
+                        ...columns(patch),
+                        // Editing a field drops its translation: what someone wrote shows as written.
+                        ...(patch.name !== undefined && patch.name !== before.name
+                            ? { nameText: null }
+                            : {}),
+                        ...(patch.description !== undefined &&
+                            (patch.description ?? null) !== before.description
+                            ? { descriptionText: null }
+                            : {}),
+                        updatedAt: now,
+                    });
+                    if (patch.userIds !== undefined)
+                        await replaceUsers(conn, id, cleanList(patch.userIds), () => ids.next(), now);
+                    if (patch.skillIds !== undefined)
+                        await attachSkills(conn, id, patch.skillIds, ids, now);
+                    const after = await require(conn, id);
+                    const changes = diffAgents(before, after);
+                    if (changes.length === 0)
+                        throw new Unchanged(before);
+                    await recordChange(conn, {
+                        id: ids.next(),
+                        agentId: id,
+                        revision: after.revision,
+                        action: 'updated',
+                        actorUserId: byUserId,
+                        changes,
+                        createdAt: now,
+                    });
+                    emit({ type: 'agent.changed', agentId: id });
+                    return after;
+                });
+            }
+            catch (error) {
+                if (error instanceof Unchanged)
+                    return error.agent;
+                throw error;
+            }
+        },
+        archive: (id, byUserId) => tx.run(async (unit) => {
+            const agent = await require(unit.conn, id);
+            if (agent.archivedAt)
+                return agent;
+            const now = clock.now().toISOString();
+            await revise(unit.conn, agent, { archivedAt: now, updatedAt: now });
+            await recordChange(unit.conn, {
+                id: ids.next(),
+                agentId: id,
+                revision: agent.revision + 1,
+                action: 'archived',
+                actorUserId: byUserId,
+                changes: [],
+                createdAt: now,
+            });
+            await deps.owned?.withdrawQueued(unit, id, byUserId);
+            unit.emit({ type: 'agent.changed', agentId: id });
+            removed(unit, agent, 'archived', byUserId);
+            return require(unit.conn, id);
+        }),
+        restore: (id, byUserId) => tx.run(async ({ conn, emit }) => {
+            const agent = await require(conn, id);
+            if (!agent.archivedAt)
+                return agent;
+            const now = clock.now().toISOString();
+            await revise(conn, agent, { archivedAt: null, updatedAt: now });
+            await recordChange(conn, {
+                id: ids.next(),
+                agentId: id,
+                revision: agent.revision + 1,
+                action: 'restored',
+                actorUserId: byUserId,
+                changes: [],
+                createdAt: now,
+            });
+            emit({ type: 'agent.changed', agentId: id });
+            return require(conn, id);
+        }),
+        remove: (id, byUserId) => tx.run(async (unit) => {
+            const { conn } = unit;
+            const agent = await require(conn, id);
+            if (!agent.archivedAt)
+                throw precondition('AGENT_NOT_ARCHIVED', 'Archive the agent before deleting it.');
+            if (deps.owned && (await deps.owned.openRuns(conn, id)) > 0)
+                throw precondition('AGENT_HAS_ACTIVE_RUNS', 'The agent still has runs that have not ended.');
+            await attachmentsRepo(conn).deleteMany({
+                filter: { scope: 'agent', scopeId: id },
+            });
+            await deps.owned?.clearVariables(conn, id);
+            await deleteAgent(conn, id);
+            unit.emit({ type: 'agent.changed', agentId: id });
+            removed(unit, agent, 'deleted', byUserId);
+        }),
+        async history(id, options = {}) {
+            const conn = tx.read();
+            await require(conn, id);
+            return listChanges(conn, people, id, options);
+        },
+        async noteVariable(conn, agentId, variable) {
+            const agent = await findAgent(conn, agentId);
+            if (!agent)
+                return;
+            await recordChange(conn, {
+                id: ids.next(),
+                agentId,
+                revision: agent.revision,
+                action: 'variables',
+                actorUserId: variable.byUserId,
+                changes: [
+                    {
+                        field: 'variable',
+                        name: variable.name,
+                        change: variable.change,
+                    },
+                ],
+                createdAt: clock.now().toISOString(),
+            });
+        },
+        mayInvoke(agent, userId) {
+            if (agent.archivedAt)
+                return false;
+            if (agent.ownerUserId === userId)
+                return true;
+            if (agent.access === 'everyone')
+                return true;
+            return agent.access === 'users' && agent.userIds.includes(userId);
+        },
+    };
+}
+//# sourceMappingURL=agent.service.js.map