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

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":"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"}

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

@@ -0,0 +1,93 @@
+import type { AgentTool } from '@nocobase/agent-protocol';
+import type { DatabaseConnection } from '@nocobase/db';
+import { z } from 'zod';
+import { type Agent, type AgentChange, type AgentName, type AgentPatch, type SystemAgentInput } from '../../../shared/agents.js';
+import { type DiscoveryPreference } from './discovery.js';
+import { type Runner } from '../../../shared/runners.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';
+/** What changing an agent accepts. */
+export declare const AgentPatchSchema: z.ZodType<AgentPatch>;
+/** What every agent discovered from runners is: the application's instructions and business actions. */
+export interface AgentDefaults {
+    readonly instructions: string | null;
+    readonly actions: readonly string[];
+}
+/** The fixed id of the agent of a tool and model, so two runners reporting it at once create one. */
+export declare function runnerAgentId(tool: AgentTool, model: string): string;
+export interface AgentService {
+    setIgnored(groups: readonly {
+        key: string;
+        expectedRevision: number;
+    }[], ignored: boolean): Promise<DiscoveryPreference[]>;
+    /** The agents not removed, by name. */
+    list(): Promise<Agent[]>;
+    /** 404 when absent or removed. */
+    get(id: string): Promise<Agent>;
+    /** Any agent by id, a removed one included (runs name it), read on `conn`. */
+    find(conn: DatabaseConnection, id: string): Promise<Agent | null>;
+    /** The names of agents by id, removed ones included, read on `conn`. */
+    names(conn: DatabaseConnection, ids: readonly string[]): Promise<Map<string, string>>;
+    /** Every agent's name, removed ones and the application's own included, read on `conn`. */
+    directory(conn: DatabaseConnection): Promise<AgentName[]>;
+    /** The agent when it can be given work: enabled, with a tool and model, read on `conn`. */
+    findWorkable(conn: DatabaseConnection, id: string): Promise<Agent | null>;
+    /** The agents that can be given work, by name, read on `conn`. */
+    listActive(conn: DatabaseConnection): Promise<Agent[]>;
+    /**
+     * Changes what an agent discovered from runners is good at, its default effort or whether it is enabled, as
+     * `byUserId`, when it is still at `patch.expectedRevision`: 409 `REVISION_CONFLICT` with the current
+     * `metadata.revision` otherwise. Enabling needs a description (400 `GOOD_AT_REQUIRED`). The application's own agents
+     * are changed through the application (400 `AGENT_MANAGED`). A patch that changes nothing changes no revision.
+     */
+    update(id: string, byUserId: string | null, patch: AgentPatch): Promise<Agent>;
+    /**
+     * Keeps an agent of the application's own as `input` says, creating it the first time; enabled, and recorded in its
+     * history when something changed.
+     */
+    ensureSystem(input: SystemAgentInput, byUserId?: string | null): Promise<Agent>;
+    /**
+     * What `runner` reports, in the transaction of its report: an agent for each tool and model it has signed in that
+     * none is kept for yet (pending), and when the others were last reported.
+     */
+    syncRunner(unit: Tx, runner: Runner): Promise<void>;
+    /** Where every discovered agent's instructions and business actions come from; returns what removes it. */
+    setDefaults(provider: () => AgentDefaults): () => void;
+    /** Writes the current defaults to every discovered agent that differs; answers how many changed. */
+    applyDefaults(options?: {
+        preserveInstructions?: boolean;
+    }): Promise<number>;
+    /** 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 work may be given to the agent: it is enabled, with a tool and model. Anyone may wake such an 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 agent's runs: disabling it withdraws its queued runs. */
+    readonly owned?: {
+        readonly withdrawQueued: (unit: Tx, agentId: string, byUserId: string | null) => Promise<void>;
+    };
+}
+/** Whether work may be given to the agent: enabled, with at least one tool and model. */
+export declare function isWorkable(agent: Agent): boolean;
+/** The tools and models a runner reports signed in, normalized, each once. */
+export declare function reportedCombos(runner: Runner): {
+    readonly tool: AgentTool;
+    readonly model: string;
+}[];
+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,452 @@
+/**
+ * Agents: one for each coding tool and model the runners report (`syncRunner`), and the application's own
+ * (`ensureSystem`). Nobody creates or deletes an agent. Someone who manages agents writes what an agent discovered from
+ * runners is good at, chooses its default reasoning effort and enables or disables it (`update`); everything else about
+ * it is the application's, the same for each (`setDefaults`: its instructions and business actions). Who may change an
+ * agent is the route's concern; the service checks the values and the revision an edit was made against, and keeps
+ * the history of every change (`agent.history.ts`).
+ *
+ * Disabling an agent withdraws its queued runs and announces `agent.removed`, so the application lets go of the work
+ * it gave the agent.
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { effortsFor, MAX_MODEL_ENTRIES, } from '../../../shared/agents.js';
+import { agentNameOf, discoveryKey } from '../../../shared/model-catalog.js';
+import { lockDiscovery, preferences, } from './discovery.js';
+import { reportedModels } from '../../../shared/runners.js';
+import { invalid, notFound, ProtocolError } from '../../kernel/errors.js';
+import { cleanList } from '../../kernel/values.js';
+import { diffAgents, listChanges, recordChange, } from './agent.history.js';
+import { agentDirectory, agentNamesOf, agentsRepo, findAgent, insertAgent, isRemoved, listAgents, reviseAgent, updateAgent, } from './agent.store.js';
+/** What changing an agent accepts. */
+export const AgentPatchSchema = z.strictObject({
+    description: z.string().max(10_000).nullable().optional().meta({
+        description: 'What it is good at: the project manager hands it work by this. Required to enable it.',
+    }),
+    effort: z.string().trim().max(32).nullable().optional().meta({
+        description: "Its default reasoning effort, one of its tool's; null for the tool's default.",
+    }),
+    enabled: z
+        .boolean()
+        .optional()
+        .meta({ description: 'Offer it work, or stop offering it.' }),
+    expectedRevision: z.number().int().min(1),
+});
+const NO_DEFAULTS = { instructions: null, actions: [] };
+/** How often a runner's report refreshes when its tools and models were last seen. */
+const REPORT_REFRESH_MS = 10 * 60_000;
+/** How many runs of one discovered agent may run at once: as many as the runners' slots allow. */
+const RUNNER_AGENT_CONCURRENCY = 100;
+/** How many attempts a run of any agent gets. */
+const AGENT_ATTEMPTS = 3;
+/** The effort a discovered agent starts with: `medium` when its tool takes it, else the tool's default. */
+function initialEffort(tool) {
+    return effortsFor({ tool }).includes('medium') ? 'medium' : null;
+}
+/** The fixed id of the agent of a tool and model, so two runners reporting it at once create one. */
+export function runnerAgentId(tool, model) {
+    const hash = createHash('sha256')
+        .update(`${tool}\u0000${model}`)
+        .digest('hex')
+        .slice(0, 20);
+    return `runner-${tool}-${hash}`;
+}
+/** 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 });
+}
+/** Whether work may be given to the agent: enabled, with at least one tool and model. */
+export function isWorkable(agent) {
+    return agent.status === 'enabled' && agent.modelEntries.length > 0;
+}
+/** The tools and models a runner reports signed in, normalized, each once. */
+export function reportedCombos(runner) {
+    const tools = [...new Set(runner.tools.map((tool) => tool.kind))];
+    return tools.flatMap((tool) => reportedModels(runner, tool).map((model) => ({ tool, model })));
+}
+export function createAgentService(deps) {
+    const { tx, ids, clock, people } = deps;
+    let defaults = () => NO_DEFAULTS;
+    const require = async (conn, id) => {
+        const agent = await findAgent(conn, id);
+        if (!agent || (await isRemoved(conn, id)))
+            throw notFound('Agent');
+        return agent;
+    };
+    const removed = (unit, agent, byUserId) => unit.emit({
+        type: 'agent.removed',
+        agentId: agent.id,
+        name: agent.name,
+        reason: 'disabled',
+        byUserId,
+    });
+    /** The defaults as stored: the instructions, and the actions each once. */
+    const currentDefaults = () => {
+        const value = defaults();
+        return {
+            instructions: value.instructions,
+            actions: cleanList(value.actions),
+        };
+    };
+    async function createRunnerAgent(unit, tool, model, now) {
+        const id = runnerAgentId(tool, model);
+        const { instructions, actions } = currentDefaults();
+        try {
+            // A savepoint: another runner's report creating the same agent at once leaves this transaction usable.
+            await unit.conn.transaction((conn) => insertAgent(conn, {
+                id,
+                name: agentNameOf(tool, model),
+                description: null,
+                nameText: null,
+                descriptionText: null,
+                avatar: null,
+                type: 'runner',
+                source: 'runner',
+                status: 'pending',
+                tool,
+                model,
+                modelEntries: [{ tool, model, effort: initialEffort(tool) }],
+                instructions,
+                runnerIds: [],
+                actions: [...actions],
+                confirmChanges: 'larger',
+                access: 'everyone',
+                ownerUserId: 'system',
+                maxConcurrentRuns: RUNNER_AGENT_CONCURRENCY,
+                maxAttempts: AGENT_ATTEMPTS,
+                toolPolicy: null,
+                lastReportedAt: now,
+                createdAt: now,
+                updatedAt: now,
+            }));
+        }
+        catch (error) {
+            if (await agentsRepo(unit.conn).findOne({ filter: { id } }))
+                return false;
+            throw error;
+        }
+        await recordChange(unit.conn, {
+            id: ids.next(),
+            agentId: id,
+            revision: 1,
+            action: 'created',
+            actorUserId: null,
+            changes: [],
+            createdAt: now,
+        });
+        return true;
+    }
+    return {
+        setIgnored: (groups, ignored) => tx.run(async ({ conn, emit }) => {
+            const result = [];
+            const lockedGroups = [];
+            // Stable ordering avoids deadlocks between overlapping batches.
+            for (const group of [...groups].sort((a, b) => a.key.localeCompare(b.key))) {
+                lockedGroups.push(await lockDiscovery(conn, group.key, group.expectedRevision));
+            }
+            const agents = await listAgents(conn);
+            for (const group of lockedGroups) {
+                const members = agents.filter((agent) => agent.source === 'runner' &&
+                    agent.tool &&
+                    agent.model &&
+                    discoveryKey(agent.tool, agent.model) === group.key);
+                if (!members.some((agent) => agent.status === 'pending') ||
+                    members.some((agent) => agent.status === 'enabled'))
+                    throw invalid('Only pending discovery groups can be ignored or restored. Reload the list.', { reason: 'DISCOVERY_NOT_PENDING' });
+                await preferences(conn).updateMany({
+                    filter: { key: group.key },
+                    values: { ignored },
+                });
+                for (const member of members)
+                    emit({ type: 'agent.changed', agentId: member.id });
+                result.push({ ...group, ignored });
+            }
+            return result;
+        }),
+        list: () => listAgents(tx.read()),
+        get: (id) => require(tx.read(), id),
+        find: findAgent,
+        names: agentNamesOf,
+        directory: agentDirectory,
+        async findWorkable(conn, id) {
+            const agent = await findAgent(conn, id);
+            if (!agent || !isWorkable(agent) || (await isRemoved(conn, id)))
+                return null;
+            return agent;
+        },
+        async listActive(conn) {
+            return (await listAgents(conn)).filter(isWorkable);
+        },
+        async update(id, byUserId, patch) {
+            const current = await require(tx.read(), id);
+            if (current.source !== 'runner')
+                throw invalid('This agent is kept by the application: change it in the application’s settings.', { reason: 'AGENT_MANAGED' });
+            const effort = patch.effort === undefined ? undefined : patch.effort;
+            const entry = current.modelEntries[0];
+            if (effort && entry && !effortsFor(entry).includes(effort))
+                throw invalid(`${entry.tool} takes no reasoning effort ${effort}: use one of ${effortsFor(entry).join(', ')}.`, { reason: 'EFFORT_UNSUPPORTED' });
+            const description = patch.description === undefined
+                ? current.description
+                : patch.description?.trim()
+                    ? patch.description.trim()
+                    : null;
+            const status = patch.enabled === undefined
+                ? current.status
+                : patch.enabled
+                    ? 'enabled'
+                    : current.status === 'pending'
+                        ? 'pending'
+                        : 'disabled';
+            if (status === 'enabled' && !description)
+                throw invalid('Write what the agent is good at before enabling it: the project manager hands it work by this.', { reason: 'GOOD_AT_REQUIRED' });
+            try {
+                return await tx.run(async (unit) => {
+                    const { conn, emit } = unit;
+                    const before = await require(conn, id);
+                    if (before.tool && before.model) {
+                        const group = await lockDiscovery(conn, discoveryKey(before.tool, before.model));
+                        if (patch.enabled && group.ignored)
+                            throw invalid('Restore this discovery group before enabling it.', { reason: 'DISCOVERY_IGNORED' });
+                    }
+                    if (patch.expectedRevision !== before.revision)
+                        throw revisionConflict(before.revision);
+                    const now = clock.now().toISOString();
+                    const modelEntries = effort === undefined
+                        ? [...before.modelEntries]
+                        : before.modelEntries.map((item, index) => index === 0 ? { ...item, effort } : item);
+                    if (!(await reviseAgent(conn, id, before.revision, {
+                        description,
+                        descriptionText: description === before.description && before.descriptionText
+                            ? {
+                                key: before.descriptionText.key,
+                                ns: before.descriptionText.ns,
+                            }
+                            : null,
+                        status,
+                        modelEntries: modelEntries.slice(0, MAX_MODEL_ENTRIES),
+                        updatedAt: now,
+                    })))
+                        throw revisionConflict((await require(conn, id)).revision);
+                    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: before.status !== after.status
+                            ? after.status === 'enabled'
+                                ? 'enabled'
+                                : 'disabled'
+                            : 'updated',
+                        actorUserId: byUserId,
+                        changes,
+                        createdAt: now,
+                    });
+                    if (before.status === 'enabled' && after.status !== 'enabled') {
+                        await deps.owned?.withdrawQueued(unit, id, byUserId);
+                        removed(unit, after, byUserId);
+                    }
+                    emit({ type: 'agent.changed', agentId: id });
+                    return after;
+                });
+            }
+            catch (error) {
+                if (error instanceof Unchanged)
+                    return error.agent;
+                throw error;
+            }
+        },
+        ensureSystem: (input, byUserId = null) => tx.run(async ({ conn, emit }) => {
+            const now = clock.now().toISOString();
+            const values = {
+                name: input.name,
+                nameText: input.nameText ? { ...input.nameText } : null,
+                description: input.description,
+                instructions: input.instructions,
+                actions: cleanList(input.actions),
+                modelEntries: input.modelEntries
+                    .slice(0, MAX_MODEL_ENTRIES)
+                    .map((entry) => ({ ...entry })),
+            };
+            const before = await findAgent(conn, input.id);
+            if (!before) {
+                await insertAgent(conn, {
+                    id: input.id,
+                    ...values,
+                    descriptionText: null,
+                    avatar: null,
+                    type: 'runner',
+                    source: 'system',
+                    status: 'enabled',
+                    tool: null,
+                    model: null,
+                    runnerIds: [],
+                    confirmChanges: 'larger',
+                    access: 'everyone',
+                    ownerUserId: 'system',
+                    maxConcurrentRuns: RUNNER_AGENT_CONCURRENCY,
+                    maxAttempts: AGENT_ATTEMPTS,
+                    toolPolicy: null,
+                    lastReportedAt: null,
+                    createdAt: now,
+                    updatedAt: now,
+                });
+                await recordChange(conn, {
+                    id: ids.next(),
+                    agentId: input.id,
+                    revision: 1,
+                    action: 'created',
+                    actorUserId: byUserId,
+                    changes: [],
+                    createdAt: now,
+                });
+                emit({ type: 'agent.changed', agentId: input.id });
+                return (await findAgent(conn, input.id));
+            }
+            const unchanged = !(await isRemoved(conn, input.id)) &&
+                before.source === 'system' &&
+                before.status === 'enabled' &&
+                before.name === values.name &&
+                JSON.stringify(before.nameText) === JSON.stringify(values.nameText) &&
+                before.description === values.description &&
+                before.instructions === values.instructions &&
+                JSON.stringify(before.actions) === JSON.stringify(values.actions) &&
+                JSON.stringify(before.modelEntries) ===
+                    JSON.stringify(values.modelEntries.map((entry) => ({
+                        tool: entry.tool,
+                        model: entry.model ?? null,
+                        effort: entry.effort ?? null,
+                    })));
+            if (unchanged)
+                return before;
+            await reviseAgent(conn, input.id, before.revision, {
+                ...values,
+                source: 'system',
+                status: 'enabled',
+                archivedAt: null,
+                deletedAt: null,
+                updatedAt: now,
+            });
+            const after = (await findAgent(conn, input.id));
+            await recordChange(conn, {
+                id: ids.next(),
+                agentId: input.id,
+                revision: after.revision,
+                action: 'updated',
+                actorUserId: byUserId,
+                changes: diffAgents(before, after),
+                createdAt: now,
+            });
+            emit({ type: 'agent.changed', agentId: input.id });
+            return after;
+        }),
+        async syncRunner(unit, runner) {
+            const combos = reportedCombos(runner);
+            if (combos.length === 0)
+                return;
+            const now = clock.now();
+            const nowText = now.toISOString();
+            const known = new Map((await agentsRepo(unit.conn).findMany({
+                filter: (f) => f.or(combos.map((combo) => f.string('id').eq(runnerAgentId(combo.tool, combo.model)))),
+            })).map((record) => [record.id, record]));
+            const created = [];
+            const stale = [];
+            for (const combo of combos) {
+                const id = runnerAgentId(combo.tool, combo.model);
+                const record = known.get(id);
+                if (!record) {
+                    if (await createRunnerAgent(unit, combo.tool, combo.model, nowText))
+                        created.push(id);
+                    continue;
+                }
+                const generated = agentNameOf(combo.tool, combo.model);
+                if (record.status === 'pending' &&
+                    record.name ===
+                        `${{ claude: 'Claude', codex: 'Codex', pi: 'Pi', opencode: 'OpenCode' }[combo.tool]} · ${combo.model.split('/').at(-1)}` &&
+                    record.name !== generated)
+                    await updateAgent(unit.conn, id, { name: generated });
+                if (!record.lastReportedAt ||
+                    now.getTime() - Date.parse(record.lastReportedAt) >= REPORT_REFRESH_MS)
+                    stale.push(id);
+            }
+            if (stale.length > 0)
+                await agentsRepo(unit.conn).updateMany({
+                    filter: (f) => f.or(stale.map((id) => f.string('id').eq(id))),
+                    values: { lastReportedAt: nowText },
+                });
+            for (const id of created)
+                unit.emit({ type: 'agent.changed', agentId: id });
+        },
+        setDefaults(provider) {
+            defaults = provider;
+            return () => {
+                if (defaults === provider)
+                    defaults = () => NO_DEFAULTS;
+            };
+        },
+        async applyDefaults(options = {}) {
+            const { instructions, actions } = currentDefaults();
+            return tx.run(async ({ conn, emit }) => {
+                const records = await agentsRepo(conn).findMany({
+                    filter: (f) => f.and([
+                        f.string('source').eq('runner'),
+                        f.date('deletedAt').empty(),
+                    ]),
+                });
+                let changed = 0;
+                for (const record of records) {
+                    const agent = (await findAgent(conn, record.id));
+                    if ((options.preserveInstructions ||
+                        agent.instructions === instructions) &&
+                        JSON.stringify(agent.actions) === JSON.stringify(actions))
+                        continue;
+                    await updateAgent(conn, record.id, {
+                        ...(options.preserveInstructions ? {} : { instructions }),
+                        actions: [...actions],
+                        updatedAt: clock.now().toISOString(),
+                    });
+                    emit({ type: 'agent.changed', agentId: record.id });
+                    changed += 1;
+                }
+                return changed;
+            });
+        },
+        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) => isWorkable(agent),
+    };
+}
+//# sourceMappingURL=agent.service.js.map