@alisio/core 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/agents/definitions.js

@@ -0,0 +1,404 @@
+/**
+ * User agent definitions as portable Markdown files, shared with other harnesses:
+ *
+ * - project scope: `<workspace>/.agents/agents/<id>.md`
+ * - global scope: `~/.agents/agents/<id>.md`
+ *
+ * The file follows the common subagent convention (Claude Code / OpenCode): YAML frontmatter with
+ * `name` (the id slug), `description`, `model` and optional keys such as `tools`, and the system
+ * prompt as the Markdown body. Alisio-only settings live under one namespaced `alisio:` key that
+ * other tools ignore. Edits go through the YAML document model, so every key (and comment) another
+ * tool wrote round-trips unchanged; only the keys Alisio owns are set or removed.
+ *
+ * Pure file logic with portable `node:fs` only; no runtime-specific APIs.
+ */
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { Document, isMap, parseDocument } from "yaml";
+/** Same identifier rule as the subagents plugin (and Claude Code agent names). */
+export const AGENT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_ID_LENGTH = 48;
+/** Built-in agent names a user file must not shadow (main `build`/`plan`, subagents). */
+export const RESERVED_AGENT_IDS = new Set(["build", "plan", "general", "explore"]);
+export const AGENT_LIMITS = {
+    name: 80,
+    description: 300,
+    instructions: 24_000,
+    model: 300,
+};
+export const AGENT_REASONING_SUMMARIES = [
+    "auto",
+    "none",
+    "concise",
+    "detailed",
+];
+export const AGENT_VERBOSITIES = ["low", "medium", "high"];
+export const AGENT_TEXT_FORMATS = ["text", "json_object", "json_schema"];
+const EFFORT = /^[a-z][a-z_-]{0,19}$/;
+/** Frontmatter key of the Alisio-only settings (ignored by other harnesses). */
+export const ALISIO_KEY = "alisio";
+/** The directory of one scope. */
+export function agentScopeDir(scope, roots) {
+    if (scope === "global")
+        return join(roots.home, ".agents", "agents");
+    if (!roots.workspace)
+        throw new Error("The project scope needs an open workspace");
+    return join(roots.workspace, ".agents", "agents");
+}
+const str = (value) => (typeof value === "string" ? value : undefined);
+/**
+ * Validates and normalizes an untrusted definition body (web API, TUI, drafts). Unknown keys are
+ * dropped; strings are trimmed; empty optional settings are omitted.
+ */
+export function validateAgentDefinitionInput(raw) {
+    const errors = [];
+    const body = (raw && typeof raw === "object" ? raw : {});
+    const name = str(body.name)?.trim() ?? "";
+    if (!name)
+        errors.push({ field: "name", message: "Name is required" });
+    else if (name.length > AGENT_LIMITS.name)
+        errors.push({ field: "name", message: `Name is limited to ${AGENT_LIMITS.name} characters` });
+    else if (!slugify(name))
+        errors.push({ field: "name", message: "Name needs at least one letter or digit" });
+    const description = str(body.description)?.trim() ?? "";
+    if (body.description !== undefined && typeof body.description !== "string")
+        errors.push({ field: "description", message: "Description must be text" });
+    if (description.length > AGENT_LIMITS.description)
+        errors.push({
+            field: "description",
+            message: `Description is limited to ${AGENT_LIMITS.description} characters`,
+        });
+    const instructions = str(body.instructions)?.trim() ?? "";
+    if (body.instructions !== undefined && typeof body.instructions !== "string")
+        errors.push({ field: "instructions", message: "Instructions must be text" });
+    if (instructions.length > AGENT_LIMITS.instructions)
+        errors.push({
+            field: "instructions",
+            message: `Instructions are limited to ${AGENT_LIMITS.instructions} characters`,
+        });
+    const model = str(body.model)?.trim() ?? "";
+    if (!model)
+        errors.push({ field: "model", message: "Model is required" });
+    else if (model.length > AGENT_LIMITS.model || /\s/.test(model))
+        errors.push({ field: "model", message: "Model must be a provider/model selector" });
+    const reasoningRaw = body.reasoning;
+    const reasoning = {};
+    if (reasoningRaw !== undefined && reasoningRaw !== null) {
+        if (typeof reasoningRaw !== "object")
+            errors.push({ field: "reasoning", message: "Reasoning must be an object" });
+        else {
+            const { effort, summary } = reasoningRaw;
+            if (effort !== undefined && effort !== null && effort !== "") {
+                if (typeof effort !== "string" || !EFFORT.test(effort))
+                    errors.push({ field: "reasoning.effort", message: "Invalid reasoning effort level" });
+                else
+                    reasoning.effort = effort;
+            }
+            if (summary !== undefined && summary !== null && summary !== "") {
+                if (!AGENT_REASONING_SUMMARIES.includes(summary))
+                    errors.push({
+                        field: "reasoning.summary",
+                        message: `Summary must be one of ${AGENT_REASONING_SUMMARIES.join(", ")}`,
+                    });
+                else
+                    reasoning.summary = summary;
+            }
+        }
+    }
+    const textRaw = body.text;
+    const text = {};
+    if (textRaw !== undefined && textRaw !== null) {
+        if (typeof textRaw !== "object")
+            errors.push({ field: "text", message: "Text must be an object" });
+        else {
+            const { format, verbosity } = textRaw;
+            const type = format && typeof format === "object" ? format.type : undefined;
+            if (format !== undefined && format !== null) {
+                if (!AGENT_TEXT_FORMATS.includes(type))
+                    errors.push({
+                        field: "text.format.type",
+                        message: `Text format must be one of ${AGENT_TEXT_FORMATS.join(", ")}`,
+                    });
+                else
+                    text.format = { type: type };
+            }
+            if (verbosity !== undefined && verbosity !== null && verbosity !== "") {
+                if (!AGENT_VERBOSITIES.includes(verbosity))
+                    errors.push({
+                        field: "text.verbosity",
+                        message: `Verbosity must be one of ${AGENT_VERBOSITIES.join(", ")}`,
+                    });
+                else
+                    text.verbosity = verbosity;
+            }
+        }
+    }
+    if (errors.length)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        value: {
+            name,
+            ...(description ? { description } : {}),
+            ...(instructions ? { instructions } : {}),
+            model,
+            ...(Object.keys(reasoning).length ? { reasoning } : {}),
+            ...(Object.keys(text).length ? { text } : {}),
+        },
+    };
+}
+/** Lowercase ASCII slug of a display name (diacritics folded), possibly empty. */
+export function slugify(name) {
+    return name
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_ID_LENGTH)
+        .replace(/-+$/g, "");
+}
+/** A fresh id for `name`: its slug, suffixed (`-2`, `-3`…) past reserved and `taken` ids. */
+export function agentIdFromName(name, taken) {
+    const base = slugify(name) || "agent";
+    const free = (id) => !taken.has(id) && !RESERVED_AGENT_IDS.has(id);
+    if (free(base))
+        return base;
+    for (let n = 2;; n++) {
+        const suffix = `-${n}`;
+        const id = `${base.slice(0, MAX_ID_LENGTH - suffix.length).replace(/-+$/g, "")}${suffix}`;
+        if (free(id))
+            return id;
+    }
+}
+/** The description written when none is given: the first sentence of the instructions. */
+export function defaultDescription(name, instructions) {
+    const first = instructions
+        .split(/\n\s*\n/)[0]
+        ?.replace(/\s+/g, " ")
+        .trim();
+    const sentence = first?.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? first ?? "";
+    const text = sentence || `${name} agent`;
+    return text.length > AGENT_LIMITS.description
+        ? `${text.slice(0, AGENT_LIMITS.description - 1).trimEnd()}…`
+        : text;
+}
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n?---[ \t]*(?:\r?\n|$)([\s\S]*)$/;
+/** Splits a Markdown agent file into its YAML document and body (no frontmatter: empty doc). */
+export function parseAgentFile(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return { doc: new Document({}), body: text.trim() };
+    const doc = parseDocument(match[1] ?? "");
+    if (doc.errors.length)
+        return undefined;
+    if (doc.contents !== null && !isMap(doc.contents))
+        return undefined;
+    if (doc.contents === null)
+        doc.contents = doc.createNode({});
+    // Bounded alias expansion (a hostile file cannot blow up `toJS`).
+    try {
+        doc.toJS({ maxAliasCount: 20 });
+    }
+    catch {
+        return undefined;
+    }
+    return { doc, body: (match[2] ?? "").trim() };
+}
+const iso = (ms) => new Date(ms).toISOString();
+const time = (value) => {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const ms = typeof value === "number" ? value : Date.parse(value);
+    return Number.isFinite(ms) ? ms : undefined;
+};
+/** The definition a parsed file describes (`id`/`scope`/`path` come from its location). */
+export function definitionFromFile(parsed, meta) {
+    const front = (parsed.doc.toJS({ maxAliasCount: 20 }) ?? {});
+    const own = (front[ALISIO_KEY] && typeof front[ALISIO_KEY] === "object" ? front[ALISIO_KEY] : {});
+    const reasoningRaw = (own.reasoning && typeof own.reasoning === "object" ? own.reasoning : {});
+    const textRaw = (own.text && typeof own.text === "object" ? own.text : {});
+    const reasoning = {};
+    if (typeof reasoningRaw.effort === "string" && EFFORT.test(reasoningRaw.effort))
+        reasoning.effort = reasoningRaw.effort;
+    if (AGENT_REASONING_SUMMARIES.includes(reasoningRaw.summary))
+        reasoning.summary = reasoningRaw.summary;
+    const text = {};
+    const format = (textRaw.format && typeof textRaw.format === "object" ? textRaw.format : {});
+    if (AGENT_TEXT_FORMATS.includes(format.type))
+        text.format = { type: format.type };
+    if (AGENT_VERBOSITIES.includes(textRaw.verbosity))
+        text.verbosity = textRaw.verbosity;
+    const displayName = (typeof own.displayName === "string" && own.displayName.trim()) ||
+        (typeof front.name === "string" && front.name.trim()) ||
+        meta.id;
+    const updatedAt = time(own.updatedAt) ?? meta.mtimeMs;
+    const createdAt = time(own.createdAt) ?? meta.birthtimeMs ?? updatedAt;
+    return {
+        id: meta.id,
+        scope: meta.scope,
+        name: displayName,
+        description: typeof front.description === "string" ? front.description.trim() : "",
+        instructions: parsed.body,
+        model: typeof front.model === "string" ? front.model.trim() : "",
+        ...(Object.keys(reasoning).length ? { reasoning } : {}),
+        ...(Object.keys(text).length ? { text } : {}),
+        path: meta.path,
+        createdAt,
+        updatedAt,
+    };
+}
+/** Sets `path` to `value`, or removes it (and then-empty parent maps) when undefined. */
+function put(doc, path, value) {
+    if (value !== undefined) {
+        doc.setIn(path, value);
+        return;
+    }
+    if (doc.hasIn(path))
+        doc.deleteIn(path);
+    for (let depth = path.length - 1; depth > 0; depth--) {
+        const parent = doc.getIn(path.slice(0, depth), true);
+        if (isMap(parent) && parent.items.length === 0)
+            doc.deleteIn(path.slice(0, depth));
+    }
+}
+/**
+ * Serializes `input` into the file's YAML document (mutating it) and returns the file text.
+ * Keys Alisio does not own are left exactly as they were.
+ */
+export function renderAgentFile(doc, id, input, times) {
+    const instructions = input.instructions?.trim() ?? "";
+    doc.set("name", id);
+    doc.set("description", input.description?.trim() || defaultDescription(input.name, instructions));
+    doc.set("model", input.model);
+    // Main-capable (OpenCode `mode: all`) so it can be the ACTIVE agent and a subagent; an existing
+    // file keeps the mode its author chose.
+    if (times.created && !doc.has("mode"))
+        doc.set("mode", "all");
+    put(doc, [ALISIO_KEY, "displayName"], input.name === id ? undefined : input.name);
+    put(doc, [ALISIO_KEY, "reasoning", "effort"], input.reasoning?.effort);
+    put(doc, [ALISIO_KEY, "reasoning", "summary"], input.reasoning?.summary);
+    put(doc, [ALISIO_KEY, "text", "format", "type"], input.text?.format?.type);
+    put(doc, [ALISIO_KEY, "text", "verbosity"], input.text?.verbosity);
+    put(doc, [ALISIO_KEY, "createdAt"], iso(times.createdAt));
+    put(doc, [ALISIO_KEY, "updatedAt"], iso(times.updatedAt));
+    const front = doc.toString({ lineWidth: 0 }).trimEnd();
+    return `---\n${front}\n---\n${instructions ? `\n${instructions}\n` : ""}`;
+}
+export class AgentNotFoundError extends Error {
+    constructor(scope, id) {
+        super(`Agent ${id} not found in the ${scope} scope`);
+    }
+}
+/** Reads and writes the agent files of one scope directory. */
+export class AgentScopeStore {
+    scope;
+    dir;
+    now;
+    constructor(scope, dir, now = Date.now) {
+        this.scope = scope;
+        this.dir = dir;
+        this.now = now;
+    }
+    pathOf(id) {
+        if (!AGENT_ID_PATTERN.test(id) || id.length > 64)
+            throw new AgentNotFoundError(this.scope, id);
+        return join(this.dir, `${id}.md`);
+    }
+    async read(id) {
+        const path = this.pathOf(id);
+        let text;
+        let stats;
+        try {
+            [text, stats] = await Promise.all([readFile(path, "utf8"), stat(path)]);
+        }
+        catch {
+            return undefined;
+        }
+        if (text.length > 64_000)
+            return undefined;
+        const parsed = parseAgentFile(text);
+        if (!parsed)
+            return undefined;
+        return {
+            parsed,
+            info: definitionFromFile(parsed, {
+                id,
+                scope: this.scope,
+                path,
+                mtimeMs: stats.mtimeMs,
+                ...(stats.birthtimeMs ? { birthtimeMs: stats.birthtimeMs } : {}),
+            }),
+        };
+    }
+    /** Every readable `<id>.md` of the scope (invalid names and unparseable files are skipped). */
+    async list() {
+        let names;
+        try {
+            names = (await readdir(this.dir)).filter((n) => n.endsWith(".md")).sort();
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const name of names.slice(0, 200)) {
+            const id = basename(name, ".md");
+            if (!AGENT_ID_PATTERN.test(id))
+                continue;
+            const found = await this.read(id);
+            if (found)
+                out.push(found.info);
+        }
+        return out;
+    }
+    async get(id) {
+        try {
+            return (await this.read(id))?.info;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async create(input, extraTaken = []) {
+        const taken = new Set([...(await this.list()).map((a) => a.id), ...extraTaken]);
+        const id = agentIdFromName(input.name, taken);
+        const now = this.now();
+        const text = renderAgentFile(new Document({}), id, input, {
+            createdAt: now,
+            updatedAt: now,
+            created: true,
+        });
+        await this.write(id, text);
+        return (await this.get(id));
+    }
+    async update(id, input) {
+        const found = await this.read(id);
+        if (!found)
+            throw new AgentNotFoundError(this.scope, id);
+        const text = renderAgentFile(found.parsed.doc, id, input, {
+            createdAt: found.info.createdAt,
+            updatedAt: Math.max(this.now(), found.info.updatedAt + 1),
+            created: false,
+        });
+        await this.write(id, text);
+        return (await this.get(id));
+    }
+    async delete(id) {
+        try {
+            await unlink(this.pathOf(id));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async write(id, text) {
+        await mkdir(this.dir, { recursive: true });
+        const path = this.pathOf(id);
+        const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(temp, text, "utf8");
+        await rename(temp, path);
+    }
+}

package/dist/agents/draft.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Assisted agent creation: one tool-less call of the ACTIVE model turns a short description into
+ * a draft definition (name, description, instructions, suggested settings) that the user reviews
+ * before saving. Nothing is persisted here.
+ */
+import type { AgentDefinitionInput, AgentDraft, ModelProvider } from "@alisio/sdk";
+export declare const AGENT_DRAFT_MAX_DESCRIPTION = 2000;
+/** The reply contract appended after the authoring guidance. */
+export declare const AGENT_DRAFT_INSTRUCTIONS: string;
+/** Where the authoring guidance came from: a discovered skill, or the bundled one. */
+export interface AgentAuthoringGuidance {
+    text: string;
+    source: string;
+}
+/**
+ * The authoring guidance: the first effective skill named like `AGENT_AUTHORING_SKILL_NAMES`
+ * (project/user/plugin skills), else the bundled `create-agent` skill.
+ */
+export declare function agentAuthoringGuidance(skills?: {
+    items: {
+        has(name: string): boolean;
+    };
+    load(name: string): Promise<string>;
+}): Promise<AgentAuthoringGuidance>;
+/**
+ * A safe draft from a model answer: unknown settings are dropped, texts are clipped to the store
+ * limits. Throws when the answer has no usable JSON object or no instructions.
+ */
+export declare function parseAgentDraft(answer: string, generatedBy: string, guidance?: string): AgentDraft;
+/** The user turn: a fresh description, or a definition to refine with optional changes. */
+export declare function agentDraftRequest(description: string, base?: Partial<Pick<AgentDefinitionInput, "name" | "description" | "instructions">>): string;
+/**
+ * Drafts an agent with one tool-less call of `provider` (the ACTIVE model): from `description`,
+ * or by refining `base` (a template or the current form) with `description` as the changes.
+ */
+export declare function generateAgentDraft(provider: ModelProvider, description: string, options?: {
+    signal?: AbortSignal;
+    maxTokens?: number;
+    guidance?: AgentAuthoringGuidance;
+    base?: Partial<Pick<AgentDefinitionInput, "name" | "description" | "instructions">>;
+}): Promise<AgentDraft>;

package/dist/agents/draft.js

@@ -0,0 +1,133 @@
+import { completeText } from "../core/compaction.js";
+import { AGENT_AUTHORING_SKILL_NAMES, CREATE_AGENT_SKILL, skillBody, } from "./create-agent-skill.js";
+import { AGENT_LIMITS, AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, defaultDescription, } from "./definitions.js";
+export const AGENT_DRAFT_MAX_DESCRIPTION = 2_000;
+/** The reply contract appended after the authoring guidance. */
+export const AGENT_DRAFT_INSTRUCTIONS = [
+    "You design agents that run inside Alisio, a coding-agent harness with tools for reading and",
+    "editing files, searching code and running processes. Follow the authoring guidance above.",
+    "Reply with ONE JSON object and nothing else, using keys:",
+    '"name" (2-5 words, Title Case), "description" (one sentence, under 200 characters),',
+    '"instructions" (the complete system prompt in Markdown, under 6000 characters),',
+    '"reasoning" ({"effort": "low"|"medium"|"high", "summary": "auto"|"none"|"concise"|"detailed"})',
+    'and "text" ({"format": {"type": "text"|"json_object"|"json_schema"}, "verbosity":',
+    '"low"|"medium"|"high"}).',
+].join(" ");
+/**
+ * The authoring guidance: the first effective skill named like `AGENT_AUTHORING_SKILL_NAMES`
+ * (project/user/plugin skills), else the bundled `create-agent` skill.
+ */
+export async function agentAuthoringGuidance(skills) {
+    for (const name of AGENT_AUTHORING_SKILL_NAMES) {
+        if (!skills?.items.has(name))
+            continue;
+        try {
+            const text = skillBody(await skills.load(name));
+            if (text)
+                return { text, source: `skill:${name}` };
+        }
+        catch {
+            /* fall back to the bundled guidance */
+        }
+    }
+    return { text: skillBody(CREATE_AGENT_SKILL), source: "bundled:create-agent" };
+}
+/** Extracts the first JSON object of a model answer (tolerating code fences and prose). */
+function firstJsonObject(text) {
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text)?.[1];
+    for (const candidate of [fenced, text]) {
+        if (!candidate)
+            continue;
+        const start = candidate.indexOf("{");
+        const end = candidate.lastIndexOf("}");
+        if (start < 0 || end <= start)
+            continue;
+        try {
+            const parsed = JSON.parse(candidate.slice(start, end + 1));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return undefined;
+}
+const clip = (value, max) => typeof value === "string" ? value.trim().slice(0, max) : "";
+/**
+ * A safe draft from a model answer: unknown settings are dropped, texts are clipped to the store
+ * limits. Throws when the answer has no usable JSON object or no instructions.
+ */
+export function parseAgentDraft(answer, generatedBy, guidance = "bundled:create-agent") {
+    const json = firstJsonObject(answer);
+    if (!json)
+        throw new Error("The model did not return a JSON agent draft; try again");
+    const instructions = clip(json.instructions, AGENT_LIMITS.instructions);
+    if (!instructions)
+        throw new Error("The model's draft has no instructions; try again");
+    const name = clip(json.name, AGENT_LIMITS.name) || "New agent";
+    const description = clip(json.description, AGENT_LIMITS.description) || defaultDescription(name, instructions);
+    const reasoningRaw = (json.reasoning && typeof json.reasoning === "object" ? json.reasoning : {});
+    const textRaw = (json.text && typeof json.text === "object" ? json.text : {});
+    const reasoning = {};
+    if (["low", "medium", "high"].includes(reasoningRaw.effort))
+        reasoning.effort = reasoningRaw.effort;
+    if (AGENT_REASONING_SUMMARIES.includes(reasoningRaw.summary))
+        reasoning.summary = reasoningRaw.summary;
+    const text = {};
+    const formatType = textRaw.format?.type;
+    if (AGENT_TEXT_FORMATS.includes(formatType))
+        text.format = { type: formatType };
+    if (AGENT_VERBOSITIES.includes(textRaw.verbosity))
+        text.verbosity = textRaw.verbosity;
+    return {
+        name,
+        description,
+        instructions,
+        ...(Object.keys(reasoning).length ? { reasoning } : {}),
+        ...(Object.keys(text).length ? { text } : {}),
+        generatedBy,
+        guidance,
+    };
+}
+/** The user turn: a fresh description, or a definition to refine with optional changes. */
+export function agentDraftRequest(description, base) {
+    if (!base?.instructions?.trim())
+        return `Write a new agent from this description:\n${description.trim()}`;
+    return [
+        "Refine this existing agent definition. Keep what works, apply the requested changes and",
+        "complete any missing required section.",
+        "",
+        `Name: ${base.name ?? ""}`,
+        `Description: ${base.description ?? ""}`,
+        "Instructions:",
+        "<<<",
+        base.instructions.trim(),
+        ">>>",
+        "",
+        `Requested changes: ${description.trim() || "none; improve it to the quality bar"}`,
+    ].join("\n");
+}
+/**
+ * Drafts an agent with one tool-less call of `provider` (the ACTIVE model): from `description`,
+ * or by refining `base` (a template or the current form) with `description` as the changes.
+ */
+export async function generateAgentDraft(provider, description, options = {}) {
+    const text = description.trim();
+    if (!text && !options.base?.instructions?.trim())
+        throw new Error("Describe the agent you want first");
+    if (text.length > AGENT_DRAFT_MAX_DESCRIPTION)
+        throw new Error(`Descriptions are limited to ${AGENT_DRAFT_MAX_DESCRIPTION} characters`);
+    const guidance = options.guidance ?? (await agentAuthoringGuidance());
+    const signal = AbortSignal.any([
+        AbortSignal.timeout(180_000),
+        ...(options.signal ? [options.signal] : []),
+    ]);
+    const answer = await completeText(provider, {
+        system: `${guidance.text}\n\n${AGENT_DRAFT_INSTRUCTIONS}`,
+        messages: [{ role: "user", text: agentDraftRequest(text, options.base) }],
+        maxTokens: options.maxTokens ?? 6_144,
+        signal,
+    });
+    return parseAgentDraft(answer, provider.model, guidance.source);
+}

package/dist/agents/service.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The agent definition service every surface (web server, TUI) uses: CRUD over the project and
+ * global `.agents/agents` scopes, the merged listing (a project agent overrides the global one
+ * with the same id) and the hot-reload of the runtime agent registry after each write.
+ *
+ * The runtime registry belongs to the subagents plugin (it discovers agent files at setup and
+ * publishes them through plugin state). After a write the service asks it to rediscover and then
+ * checks whether the saved file is actually loaded, so callers report `live: true` only when the
+ * change is usable by the next prompt; otherwise they must tell the user to restart.
+ */
+import type { AgentDefinitionInfo, AgentDefinitionInput, AgentScope } from "@alisio/sdk";
+/** The runtime registry the service refreshes (implemented by the application). */
+export interface AgentRegistry {
+    /** Rediscovers agent files; false when no registry can reload (e.g. subagents plugin off). */
+    reload(): Promise<boolean>;
+    /** Absolute paths of the agent files currently loaded, or undefined when unknown. */
+    loadedPaths(): string[] | undefined;
+}
+export interface AgentChange<T> {
+    result: T;
+    /**
+     * The runtime registry reflects the change now (new prompts use it). False: the file is saved,
+     * but Alisio must restart (or the workspace must be trusted / the plugin enabled) to use it.
+     */
+    live: boolean;
+}
+export interface AgentDefinitionServiceOptions {
+    /** Workspace root; without it only the global scope exists. */
+    workspace?: string;
+    /** Home directory of the global scope (`os.homedir()`). */
+    home: string;
+    registry?: AgentRegistry;
+    now?: () => number;
+}
+/** Applies the project-over-global precedence and marks both sides of an override. */
+export declare function mergeAgentScopes(project: AgentDefinitionInfo[], global: AgentDefinitionInfo[]): AgentDefinitionInfo[];
+export declare class AgentDefinitionService {
+    private readonly options;
+    private readonly stores;
+    constructor(options: AgentDefinitionServiceOptions);
+    /** Scopes available here: `project` only with a workspace. */
+    get scopes(): AgentScope[];
+    /** The scope new agents default to: the project when a workspace is open. */
+    get defaultScope(): AgentScope;
+    dir(scope: AgentScope): string;
+    private store;
+    list(): Promise<AgentDefinitionInfo[]>;
+    get(scope: AgentScope, id: string): Promise<AgentDefinitionInfo | undefined>;
+    create(scope: AgentScope, input: AgentDefinitionInput): Promise<AgentChange<AgentDefinitionInfo>>;
+    update(scope: AgentScope, id: string, input: AgentDefinitionInput): Promise<AgentChange<AgentDefinitionInfo>>;
+    delete(scope: AgentScope, id: string): Promise<AgentChange<boolean>>;
+    /** Asks the runtime registry to rediscover agent files (false: nothing could reload). */
+    reload(): Promise<boolean>;
+    /** Whether the runtime registry has `path` loaded (false when unknown). */
+    isLoaded(path: string): boolean;
+    private settle;
+}