@alisio/alisio-code 0.1.0-alpha.23 → 0.1.0-alpha.25

package/dist/tui/agent-manager.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure logic of the TUI agent manager (`/agents`): argument parsing, the agent picker rows and
+ * their filter, and the editor form with capability-driven options. Rendering and I/O live in
+ * `app.ts`; agent files go through the core `AgentDefinitionService` shared with the web server.
+ */
+import type { AgentDefinitionInfo, AgentDefinitionInput, AgentDraft, AgentModelCapabilities, AgentReasoningSummary, AgentScope, AgentTemplateInfo } from "@alisio/core";
+import { type ActiveAgent } from "@alisio/core";
+/** Verbs the TUI owns; any other `/agents <verb>` goes to the subagents plugin's command. */
+export type AgentsCommand = {
+    kind: "picker";
+} | {
+    kind: "new";
+    description?: string;
+} | {
+    kind: "templates";
+} | {
+    kind: "manage";
+} | {
+    kind: "edit";
+    id: string;
+    scope?: AgentScope;
+} | {
+    kind: "delete";
+    id: string;
+    scope?: AgentScope;
+} | {
+    kind: "plugin";
+    args: string;
+};
+/**
+ * `/agents` → picker; `/agents new [description]` (assisted when a description is given),
+ * `/agents templates`, `/agents manage`, `/agents edit|delete <id> [project|global]`. Anything
+ * else (`list`, `defs`, `reload`, `open`, `cancel`…) belongs to the subagents plugin.
+ */
+export declare function parseAgentsArgs(args: string): AgentsCommand;
+/** "Project" / "Global" for agent files, "Built-in" / "Plugin" / "User" otherwise. */
+export declare function agentBadge(agent: Pick<ActiveAgent, "source"> & {
+    path?: string;
+}, workspace: string, home: string): string;
+export interface PickerRow {
+    value: string;
+    label: string;
+    description?: string;
+}
+/** Action rows shown above the agents in the `/agents` picker. */
+export declare const AGENT_PICKER_ACTIONS: PickerRow[];
+/** Picker rows: name, badge and markers in the label; description below. */
+export declare function agentPickerRows(agents: Array<ActiveAgent & {
+    path?: string;
+}>, activeId: string, roots: {
+    workspace: string;
+    home: string;
+}): PickerRow[];
+/** Case-insensitive substring match of every query word on the label and description. */
+export declare function filterAgentRows<T extends {
+    label: string;
+    description?: string;
+    value: string;
+}>(rows: ReadonlyArray<T>, query: string): T[];
+/** The editable state of one agent in the TUI editor. */
+export interface AgentForm {
+    scope: AgentScope;
+    /** Set when editing a saved agent. */
+    id?: string;
+    name: string;
+    description: string;
+    instructions: string;
+    model: string;
+    reasoning: {
+        effort?: string;
+        summary?: AgentReasoningSummary;
+    };
+    text: {
+        format?: "text" | "json_object" | "json_schema";
+        verbosity?: "low" | "medium" | "high";
+    };
+}
+export declare function emptyAgentForm(scope: AgentScope, model: string): AgentForm;
+export declare function formFromTemplate(template: AgentTemplateInfo, scope: AgentScope, model: string): AgentForm;
+export declare function formFromDefinition(definition: AgentDefinitionInfo): AgentForm;
+/** Applies a model draft to the form (keeps scope, id and model). */
+export declare function applyDraft(form: AgentForm, draft: AgentDraft): AgentForm;
+/** The API/service body of a form, fitted to the model's capabilities. */
+export declare function formToInput(form: AgentForm, capabilities?: AgentModelCapabilities): AgentDefinitionInput;
+/** Validation errors of a form (empty when it can be saved). */
+export declare function formErrors(form: AgentForm): string[];
+/** One-line editing of multi-line text: newlines shown and typed as `\n`. */
+export declare const encodeMultiline: (text: string) => string;
+export declare const decodeMultiline: (text: string) => string;
+export type AgentField = "scope" | "name" | "description" | "instructions" | "model" | "effort" | "summary" | "verbosity" | "format" | "refine" | "save" | "cancel";
+/**
+ * Editor rows. Settings the model does not support are shown as "not supported by this model"
+ * (their value is ignored on save); `dirty` enables the Save row.
+ */
+export declare function agentEditorRows(form: AgentForm, capabilities: AgentModelCapabilities, options: {
+    creating: boolean;
+    scopes: AgentScope[];
+    dirty: boolean;
+}): Array<PickerRow & {
+    value: AgentField;
+}>;
+/** Choice rows of a select field, honoring the model capabilities. */
+export declare function agentFieldChoices(field: "effort" | "summary" | "verbosity" | "format", capabilities: AgentModelCapabilities): PickerRow[];
+/** Whether a field can be edited for the model (unsupported settings are read-only). */
+export declare function agentFieldSupported(field: "effort" | "summary" | "verbosity", capabilities: AgentModelCapabilities): boolean;

package/dist/tui/agent-manager.js

@@ -0,0 +1,269 @@
+import { AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, DEFAULT_AGENT_ID, fitAgentSettings, validateAgentDefinitionInput, } from "@alisio/core";
+/**
+ * `/agents` → picker; `/agents new [description]` (assisted when a description is given),
+ * `/agents templates`, `/agents manage`, `/agents edit|delete <id> [project|global]`. Anything
+ * else (`list`, `defs`, `reload`, `open`, `cancel`…) belongs to the subagents plugin.
+ */
+export function parseAgentsArgs(args) {
+    const text = args.trim();
+    if (!text)
+        return { kind: "picker" };
+    const [verb = "", ...rest] = text.split(/\s+/);
+    const tail = text.slice(verb.length).trim();
+    const scope = (value) => value === "project" || value === "global" ? value : undefined;
+    switch (verb.toLowerCase()) {
+        case "new":
+        case "create":
+            return tail ? { kind: "new", description: tail } : { kind: "new" };
+        case "templates":
+        case "template":
+            return { kind: "templates" };
+        case "manage":
+            return { kind: "manage" };
+        case "edit":
+        case "delete":
+        case "rm": {
+            const [id, where] = rest;
+            if (!id)
+                return { kind: "manage" };
+            const found = scope(where);
+            return {
+                kind: verb.toLowerCase() === "edit" ? "edit" : "delete",
+                id,
+                ...(found ? { scope: found } : {}),
+            };
+        }
+        default:
+            return { kind: "plugin", args: text };
+    }
+}
+/** "Project" / "Global" for agent files, "Built-in" / "Plugin" / "User" otherwise. */
+export function agentBadge(agent, workspace, home) {
+    if (agent.source === "builtin")
+        return "Built-in";
+    if (agent.source === "plugin")
+        return "Plugin";
+    const path = agent.path ?? "";
+    if (path.startsWith(`${workspace}/`) || path.startsWith(`${workspace}\\`))
+        return "Project";
+    if (path.startsWith(`${home}/`) || path.startsWith(`${home}\\`))
+        return "Global";
+    return "User";
+}
+/** Action rows shown above the agents in the `/agents` picker. */
+export const AGENT_PICKER_ACTIONS = [
+    {
+        value: "__agents:new",
+        label: "+ Create agent…",
+        description: "Blank, from a template or written by Alisio",
+    },
+    {
+        value: "__agents:manage",
+        label: "✎ Manage saved agents…",
+        description: "Edit or delete project and global agents",
+    },
+];
+/** Picker rows: name, badge and markers in the label; description below. */
+export function agentPickerRows(agents, activeId, roots) {
+    return agents.map((agent) => ({
+        value: agent.id,
+        label: [
+            agent.name,
+            `[${agentBadge(agent, roots.workspace, roots.home)}]`,
+            agent.id === activeId ? "(current)" : undefined,
+            agent.id === DEFAULT_AGENT_ID ? "(default)" : undefined,
+            agent.readOnly ? "read-only" : undefined,
+        ]
+            .filter(Boolean)
+            .join(" "),
+        description: [agent.description, agent.model ? `model: ${agent.model}` : undefined]
+            .filter(Boolean)
+            .join(" · "),
+    }));
+}
+/** Case-insensitive substring match of every query word on the label and description. */
+export function filterAgentRows(rows, query) {
+    const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return [...rows];
+    return rows.filter((row) => {
+        const haystack = `${row.value} ${row.label} ${row.description ?? ""}`.toLowerCase();
+        return words.every((word) => haystack.includes(word));
+    });
+}
+export function emptyAgentForm(scope, model) {
+    return {
+        scope,
+        name: "New agent",
+        description: "",
+        instructions: "",
+        model,
+        reasoning: {},
+        text: {},
+    };
+}
+const settingsOf = (source) => ({
+    reasoning: {
+        ...(source.reasoning?.effort ? { effort: source.reasoning.effort } : {}),
+        ...(source.reasoning?.summary ? { summary: source.reasoning.summary } : {}),
+    },
+    text: {
+        ...(source.text?.format?.type ? { format: source.text.format.type } : {}),
+        ...(source.text?.verbosity ? { verbosity: source.text.verbosity } : {}),
+    },
+});
+export function formFromTemplate(template, scope, model) {
+    return {
+        scope,
+        name: template.name,
+        description: template.description,
+        instructions: template.instructions,
+        model,
+        ...settingsOf(template),
+    };
+}
+export function formFromDefinition(definition) {
+    return {
+        scope: definition.scope,
+        id: definition.id,
+        name: definition.name,
+        description: definition.description,
+        instructions: definition.instructions,
+        model: definition.model,
+        ...settingsOf(definition),
+    };
+}
+/** Applies a model draft to the form (keeps scope, id and model). */
+export function applyDraft(form, draft) {
+    return {
+        ...form,
+        name: draft.name,
+        description: draft.description,
+        instructions: draft.instructions,
+        ...settingsOf(draft),
+    };
+}
+/** The API/service body of a form, fitted to the model's capabilities. */
+export function formToInput(form, capabilities) {
+    const input = {
+        name: form.name.trim(),
+        ...(form.description.trim() ? { description: form.description.trim() } : {}),
+        ...(form.instructions.trim() ? { instructions: form.instructions.trim() } : {}),
+        model: form.model.trim(),
+        ...(form.reasoning.effort || form.reasoning.summary
+            ? {
+                reasoning: {
+                    ...(form.reasoning.effort ? { effort: form.reasoning.effort } : {}),
+                    ...(form.reasoning.summary ? { summary: form.reasoning.summary } : {}),
+                },
+            }
+            : {}),
+        ...(form.text.format || form.text.verbosity
+            ? {
+                text: {
+                    ...(form.text.format ? { format: { type: form.text.format } } : {}),
+                    ...(form.text.verbosity ? { verbosity: form.text.verbosity } : {}),
+                },
+            }
+            : {}),
+    };
+    return capabilities ? fitAgentSettings(input, capabilities) : input;
+}
+/** Validation errors of a form (empty when it can be saved). */
+export function formErrors(form) {
+    const result = validateAgentDefinitionInput(formToInput(form));
+    return result.ok ? [] : result.errors.map((e) => e.message);
+}
+/** One-line editing of multi-line text: newlines shown and typed as `\n`. */
+export const encodeMultiline = (text) => text.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+export const decodeMultiline = (text) => text.replace(/\\(\\|n)/g, (_, c) => (c === "n" ? "\n" : "\\"));
+const clip = (text, max = 60) => {
+    const line = text.replace(/\s+/g, " ").trim();
+    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+/**
+ * Editor rows. Settings the model does not support are shown as "not supported by this model"
+ * (their value is ignored on save); `dirty` enables the Save row.
+ */
+export function agentEditorRows(form, capabilities, options) {
+    const unsupported = "not supported by this model";
+    const rows = [];
+    if (options.creating && options.scopes.length > 1)
+        rows.push({
+            value: "scope",
+            label: `Scope: ${form.scope === "project" ? "Project" : "Global"}`,
+            description: "Project: .agents/agents in this workspace · Global: ~/.agents/agents",
+        });
+    rows.push({ value: "name", label: `Name: ${form.name || "(empty)"}` }, {
+        value: "description",
+        label: `Description: ${clip(form.description) || "(derived from instructions)"}`,
+    }, {
+        value: "instructions",
+        label: `Instructions: ${clip(form.instructions) || "(empty)"}`,
+        description: `${form.instructions.length} characters`,
+    }, { value: "model", label: `Model: ${form.model || "(choose one)"}` }, {
+        value: "effort",
+        label: `Reasoning effort: ${capabilities.reasoning ? (form.reasoning.effort ?? "model default") : "—"}`,
+        ...(capabilities.reasoning ? {} : { description: unsupported }),
+    }, {
+        value: "summary",
+        label: `Reasoning summary: ${capabilities.summary ? (form.reasoning.summary ?? "auto") : "—"}`,
+        ...(capabilities.summary ? {} : { description: unsupported }),
+    }, {
+        value: "verbosity",
+        label: `Verbosity: ${capabilities.verbosity ? (form.text.verbosity ?? "default") : "—"}`,
+        ...(capabilities.verbosity ? {} : { description: unsupported }),
+    }, { value: "format", label: `Text format: ${form.text.format ?? "text"}` }, {
+        value: "refine",
+        label: "✦ Refine with Alisio…",
+        description: "The active model rewrites the instructions to the authoring standards",
+    });
+    const errors = formErrors(form);
+    rows.push({
+        value: "save",
+        label: options.dirty && !errors.length
+            ? "✓ Save agent definition"
+            : "✓ Save agent definition (nothing to save)",
+        ...(errors.length
+            ? { description: errors.join("; ") }
+            : options.dirty
+                ? {}
+                : { description: "No unsaved changes" }),
+    });
+    rows.push({ value: "cancel", label: "✗ Close editor" });
+    return rows;
+}
+/** Choice rows of a select field, honoring the model capabilities. */
+export function agentFieldChoices(field, capabilities) {
+    const levels = field === "effort"
+        ? capabilities.effortLevels
+        : field === "summary"
+            ? AGENT_REASONING_SUMMARIES
+            : field === "verbosity"
+                ? AGENT_VERBOSITIES
+                : AGENT_TEXT_FORMATS.filter((format) => capabilities.textFormats.includes(format));
+    return [
+        ...levels.map((value) => ({
+            value,
+            label: field === "format"
+                ? value === "json_object"
+                    ? "JSON"
+                    : value === "json_schema"
+                        ? "JSON Schema"
+                        : "Text"
+                : value,
+            ...(field === "effort" && value === capabilities.defaultEffort
+                ? { description: "model default" }
+                : {}),
+        })),
+        ...(field === "format" ? [] : [{ value: "!clear", label: "(use the default)" }]),
+    ];
+}
+/** Whether a field can be edited for the model (unsupported settings are read-only). */
+export function agentFieldSupported(field, capabilities) {
+    return field === "effort"
+        ? capabilities.reasoning
+        : field === "summary"
+            ? capabilities.summary
+            : capabilities.verbosity;
+}

package/dist/tui/app.d.ts

@@ -1,4 +1,4 @@
-import type { AppOptions } from "@alisio/core";
+import { type AppOptions } from "@alisio/core";
 import { type Component, type SelectItem } from "@earendil-works/pi-tui";
 /**
  * Inline selection list with type-to-filter, rendered above the editor.
@@ -15,6 +15,8 @@ export declare class Picker implements Component {
     private readonly onCancelPick;
     private filterable;
     private detail?;
+    /** Custom filter (default: value prefix, keeping group headers). */
+    private readonly match?;
     private list;
     private filter;
     /** Full item sequence (group headers + rows) before any filtering. */
@@ -25,7 +27,9 @@ export declare class Picker implements Component {
     private index;
     /** Picker height target: counted on real rows only, so headers never stretch the list. */
     private readonly maxVisible;
-    constructor(title: string, items: SelectItem[], onSelectItem: (item: SelectItem) => void, onCancelPick: () => void, filterable?: boolean, detail?: string | undefined);
+    constructor(title: string, items: SelectItem[], onSelectItem: (item: SelectItem) => void, onCancelPick: () => void, filterable?: boolean, detail?: string | undefined, 
+    /** Custom filter (default: value prefix, keeping group headers). */
+    match?: ((items: SelectItem[], filter: string) => SelectItem[]) | undefined);
     /** Copies items, dimming group-header labels (style helpers stay plain under NO_COLOR). */
     private static displayItems;
     /** (Re)builds the SelectList over the filtered display sequence; selection starts on a row. */

package/dist/tui/app.js

@@ -1,7 +1,9 @@
 import { homedir } from "node:os";
+import { AGENT_TEMPLATES, agentAuthoringGuidance, agentCommandDescriptors, agentIdFromCommand, agentModelCapabilities, agentModelLabels, agentModelOptions, generateAgentDraft, } from "@alisio/core";
 import { CombinedAutocompleteProvider, Container, Editor, getImageDimensions, getNativeClipboard, Key, MouseRegion, matchesKey, ProcessTerminal, ScrollView, SelectList, TuiAltScreen, truncateToWidth, VStack, } from "@earendil-works/pi-tui";
 import { loadVersion } from "../version.js";
-import { activeAgentCatalog, agentPickerItems, agentRunOptions, mainAgentFromRecord, resolveActiveAgent, } from "./agents.js";
+import { AGENT_PICKER_ACTIONS, agentEditorRows, agentFieldChoices, agentFieldSupported, agentPickerRows, applyDraft, decodeMultiline, emptyAgentForm, encodeMultiline, filterAgentRows, formErrors, formFromDefinition, formFromTemplate, formToInput, parseAgentsArgs, } from "./agent-manager.js";
+import { activeAgentCatalog, agentRunOptions, mainAgentFromRecord, resolveActiveAgent, } from "./agents.js";
 import { MAX_ATTACHMENTS_PER_MESSAGE, MAX_IMAGE_BYTES, pasteImageFromClipboard, removeLastAttachment, toApiAttachment, } from "./attachments.js";
 import { BTW_DESCRIPTION, BTW_USAGE, btwBrowser, btwPending } from "./btw.js";
 import { copyText, nodeSpawn } from "./clipboard.js";
@@ -33,6 +35,7 @@ export class Picker {
     onCancelPick;
     filterable;
     detail;
+    match;
     list = new SelectList([], 1, selectListTheme);
     filter = "";
     /** Full item sequence (group headers + rows) before any filtering. */
@@ -43,12 +46,15 @@ export class Picker {
     index = 0;
     /** Picker height target: counted on real rows only, so headers never stretch the list. */
     maxVisible;
-    constructor(title, items, onSelectItem, onCancelPick, filterable = false, detail) {
+    constructor(title, items, onSelectItem, onCancelPick, filterable = false, detail, 
+    /** Custom filter (default: value prefix, keeping group headers). */
+    match) {
         this.title = title;
         this.onSelectItem = onSelectItem;
         this.onCancelPick = onCancelPick;
         this.filterable = filterable;
         this.detail = detail;
+        this.match = match;
         this.allItems = items;
         this.maxVisible = Math.min(10, Math.max(1, items.filter((item) => !isGroupHeader(item)).length));
         this.resetList();
@@ -59,7 +65,11 @@ export class Picker {
     }
     /** (Re)builds the SelectList over the filtered display sequence; selection starts on a row. */
     resetList() {
-        this.items = Picker.displayItems(this.filter ? visibleGroupedItems(this.allItems, this.filter) : this.allItems);
+        this.items = Picker.displayItems(this.filter
+            ? this.match
+                ? this.match(this.allItems, this.filter)
+                : visibleGroupedItems(this.allItems, this.filter)
+            : this.allItems);
         this.list = new SelectList(this.items, this.maxVisible, selectListTheme);
         this.list.onSelect = (item) => {
             if (!isGroupHeader(item))
@@ -684,7 +694,8 @@ export async function runTui(options) {
         // read-only agent narrows the run to reads (no approvals). The persisted reasoning effort is
         // resolved against the ACTIVE model and sent when the model advertises supported levels.
         const agent = currentAgent();
-        const effort = currentEffort();
+        // An explicit /effort wins; otherwise the agent's own default effort (agentRunOptions) is kept.
+        const effort = app.config.agents.effort || !agent.effort ? currentEffort() : undefined;
         return task((signal) => app.runner.run(session, prompt, signal, {
             ...agentRunOptions(agent),
             ...(effort ? { reasoningEffort: effort } : {}),
@@ -1160,11 +1171,20 @@ export async function runTui(options) {
     const openAgentsPicker = () => {
         const agents = mainAgents();
         const current = currentAgent();
-        showPicker(new Picker("Active agent", agentPickerItems(agents, current.id), (item) => {
+        const rows = [...AGENT_PICKER_ACTIONS, ...agentPickerRows(agents, current.id, agentRoots())];
+        showPicker(new Picker("Agents", rows, (item) => {
+            if (item.value === "__agents:new") {
+                closePicker();
+                return void newAgentFlow().catch(error);
+            }
+            if (item.value === "__agents:manage") {
+                closePicker();
+                return void manageAgents().catch(error);
+            }
             const agent = agents.find((candidate) => candidate.id === item.value);
             if (agent)
                 void applyActiveAgent(agent);
-        }, closePicker, true, "Changing the active agent takes effect from the next prompt; the current session is kept unless the agent declares a different model."));
+        }, closePicker, true, "Type to search by name or description. Selecting an agent activates it from the next prompt; build (default) returns to the default Alisio agent.", (items, filter) => filterAgentRows(items, filter)));
     };
     const applyActiveAgent = (agent) => {
         void (async () => {
@@ -1200,6 +1220,424 @@ export async function runTui(options) {
             }
         })();
     };
+    // ---- Agent manager: project/global `.agents/agents` files (shared core service) ----------
+    const agentRoots = () => ({ workspace: app.workspace, home: homedir() });
+    let agentModels;
+    /** Configured models with capabilities (cached per process; the running model always listed). */
+    const loadAgentModels = async () => {
+        if (agentModels)
+            return agentModels;
+        let options = [];
+        try {
+            options = agentModelOptions(await app.listAvailableModels(), {
+                ...(app.providerInfo?.profileName ? { profile: app.providerInfo.profileName } : {}),
+                ...(app.providerInfo?.id ? { provider: app.providerInfo.id } : {}),
+                model: view.model,
+            });
+        }
+        catch {
+            /* configured catalogs unavailable: offer the running model only */
+        }
+        if (!options.some((option) => option.active)) {
+            const capabilities = agentModelCapabilities(modelCatalog.get(view.model) ?? { id: view.model });
+            options.unshift({
+                reference: view.model,
+                provider: app.provider.id,
+                profile: app.providerInfo?.profileName ?? "",
+                providerName: app.providers.get(activeProvider?.id ?? "")?.name ?? app.provider.id,
+                id: view.model,
+                active: true,
+                capabilities,
+                labels: agentModelLabels(capabilities),
+            });
+        }
+        agentModels = options;
+        return options;
+    };
+    const capabilitiesOf = (models, reference) => models.find((m) => m.reference === reference || m.id === reference)?.capabilities ??
+        agentModelCapabilities(undefined);
+    const defaultAgentModel = (models) => models.find((m) => m.active)?.reference ?? view.model;
+    /**
+     * "Building with Alisio": one tool-less call of the ACTIVE model writes (or refines) the agent
+     * with the authoring guidance (a discovered `create-agent` skill, else the bundled one). Runs as
+     * a task, so Esc cancels it; failures are reported and leave the form untouched.
+     */
+    const buildWithAlisio = async (description, base) => {
+        let draft;
+        flashHint("◐ Building with Alisio… writing the agent instructions · Esc to cancel", 180_000);
+        await task(async (signal) => {
+            draft = await generateAgentDraft(app.provider, description, {
+                signal,
+                guidance: await agentAuthoringGuidance(app.skills),
+                ...(base
+                    ? {
+                        base: {
+                            name: base.name,
+                            description: base.description,
+                            instructions: base.instructions,
+                        },
+                    }
+                    : {}),
+            });
+        });
+        flashHint(draft
+            ? `Draft by ${draft.generatedBy} (${draft.guidance}). Review it, then save.`
+            : "Building with Alisio stopped; nothing was changed.", 5000);
+        return draft;
+    };
+    /** Saves a form; reports honestly whether the running registry already uses the change. */
+    const saveAgentForm = async (form, models) => {
+        const input = formToInput(form, capabilitiesOf(models, form.model));
+        const change = form.id
+            ? await app.agentDefinitions.update(form.scope, form.id, input)
+            : await app.agentDefinitions.create(form.scope, input);
+        editor.setAutocompleteProvider(buildSlashCompletionProvider());
+        notice(change.live
+            ? `Agent ${change.result.name} saved to ${change.result.path} and available now: /agent:${change.result.id}.`
+            : `Agent ${change.result.name} saved to ${change.result.path}. Restart Alisio to use it${form.scope === "project" ? " (project agents also need a trusted workspace)" : ""}.`);
+        return change;
+    };
+    /** Starts a fresh session with `id` as the active agent (the "Try it" action). */
+    const tryAgentInNewSession = async (id) => {
+        const agent = mainAgents().find((candidate) => candidate.id === id);
+        if (!agent)
+            return notice(`Agent ${id} is not loaded in this process; restart Alisio to try it.`);
+        await endSession("clear");
+        await app.updateSetting("agents.active", agent.id);
+        let created;
+        if (agent.model && agent.model !== view.model)
+            created = await app.switchModel(agent.model).catch(() => undefined);
+        if (created) {
+            activeProvider = app.providerInfo;
+            modelList = undefined;
+            session = created.id;
+            reset(initialViewState(created.model));
+        }
+        else {
+            session = app.store.create(app.workspace, app.provider.id, view.model).id;
+            reset(initialViewState(view.model));
+        }
+        notice(`New session ${session} with agent ${agent.name}. Type a prompt to try it.`);
+        void app.herdr.report("idle", session);
+        refreshEffort();
+        refreshEstimate();
+    };
+    /** After the first save: try the agent in a new session (default) or keep editing. */
+    const offerTryAgent = async (form, models, live) => {
+        const choice = await askChoice(`Agent ${form.name} created`, live
+            ? [
+                { value: "try", label: "▶ Try it in a new session", description: "Default" },
+                { value: "stay", label: "Stay in editor" },
+            ]
+            : [{ value: "stay", label: "Stay in editor", description: "Restart Alisio to try it" }]);
+        if (choice === "try" && form.id)
+            return tryAgentInNewSession(form.id);
+        if (choice === "stay")
+            return openAgentEditor(form, models, form);
+    };
+    /** The editor: one picker row per field; each edit returns to it. Esc closes. */
+    const openAgentEditor = async (initial, models, saved) => {
+        let form = initial;
+        let baseline = saved ? JSON.stringify(saved) : undefined;
+        const show = () => {
+            const capabilities = capabilitiesOf(models, form.model);
+            const dirty = baseline === undefined || JSON.stringify(form) !== baseline;
+            showPicker(new Picker(form.id ? `Agents › ${form.name}` : "Agents › New agent", agentEditorRows(form, capabilities, {
+                creating: !form.id,
+                scopes: app.agentDefinitions.scopes,
+                dirty,
+            }), (item) => {
+                closePicker();
+                void edit(item.value, dirty).catch((cause) => {
+                    error(cause);
+                    show();
+                });
+            }, closePicker, false, `${form.scope === "project" ? "Project" : "Global"} scope · ${shortenPath(app.agentDefinitions.dir(form.scope), homedir())}`));
+        };
+        const input = (label, initialValue, placeholder, hint) => askInput({
+            provider: "agent",
+            title: form.id ? `Agents › ${form.name}` : "Agents › New agent",
+            label,
+            initial: initialValue,
+            placeholder,
+            ...(hint ? { hint } : {}),
+            step: 1,
+            steps: 1,
+        });
+        const edit = async (field, dirty) => {
+            const capabilities = capabilitiesOf(models, form.model);
+            switch (field) {
+                case "scope": {
+                    const scope = await askChoice("Scope", app.agentDefinitions.scopes.map((value) => ({
+                        value,
+                        label: value === "project" ? "Project" : "Global",
+                        description: app.agentDefinitions.dir(value),
+                    })));
+                    if (scope === "project" || scope === "global")
+                        form = { ...form, scope };
+                    break;
+                }
+                case "name": {
+                    const value = await input("Name", form.name, "New agent");
+                    if (value !== undefined)
+                        form = { ...form, name: value.trim() };
+                    break;
+                }
+                case "description": {
+                    const value = await input("Description", form.description, "One sentence: what this agent does");
+                    if (value !== undefined)
+                        form = { ...form, description: value.trim() };
+                    break;
+                }
+                case "instructions": {
+                    const value = await input("Instructions", encodeMultiline(form.instructions), "Describe desired model behavior (tone, tool usage, response style)", "Type \\n for a new line. ✦ Refine with Alisio writes them for you.");
+                    if (value !== undefined)
+                        form = { ...form, instructions: decodeMultiline(value) };
+                    break;
+                }
+                case "model": {
+                    const value = await askChoice("Model", models.map((m) => ({
+                        value: m.reference,
+                        label: `${m.name ?? m.id} · ${m.providerName}${m.active ? " (active)" : ""}${m.reference === form.model ? " ✓" : ""}`,
+                        description: m.labels.join(" · ") || "capabilities not declared by the provider",
+                    })));
+                    if (value) {
+                        const fitted = formToInput({ ...form, model: value }, capabilitiesOf(models, value));
+                        form = {
+                            ...form,
+                            model: value,
+                            reasoning: { ...(fitted.reasoning ?? {}) },
+                            text: {
+                                ...(fitted.text?.format ? { format: fitted.text.format.type } : {}),
+                                ...(fitted.text?.verbosity ? { verbosity: fitted.text.verbosity } : {}),
+                            },
+                        };
+                    }
+                    break;
+                }
+                case "effort":
+                case "summary":
+                case "verbosity":
+                case "format": {
+                    if (field !== "format" && !agentFieldSupported(field, capabilities)) {
+                        flashHint(`${form.model} does not support this setting.`);
+                        break;
+                    }
+                    const value = await askChoice(field, agentFieldChoices(field, capabilities));
+                    if (value === undefined)
+                        break;
+                    const clear = value === "!clear" ? undefined : value;
+                    if (field === "effort")
+                        form = { ...form, reasoning: { ...form.reasoning, effort: clear } };
+                    if (field === "summary")
+                        form = {
+                            ...form,
+                            reasoning: { ...form.reasoning, summary: clear },
+                        };
+                    if (field === "verbosity")
+                        form = {
+                            ...form,
+                            text: { ...form.text, verbosity: clear },
+                        };
+                    if (field === "format")
+                        form = {
+                            ...form,
+                            text: { ...form.text, format: clear },
+                        };
+                    break;
+                }
+                case "refine": {
+                    const changes = await input("What should change? (optional)", "", "e.g. focus on security, answer in Spanish");
+                    if (changes === undefined)
+                        break;
+                    const draft = await buildWithAlisio(changes, form);
+                    if (draft)
+                        form = applyDraft(form, draft);
+                    break;
+                }
+                case "save": {
+                    const errors = formErrors(form);
+                    if (errors.length) {
+                        flashHint(errors.join("; "), 5000);
+                        break;
+                    }
+                    if (!dirty) {
+                        flashHint("No unsaved changes");
+                        break;
+                    }
+                    const creating = !form.id;
+                    const change = await saveAgentForm(form, models);
+                    form = { ...form, id: change.result.id, name: change.result.name };
+                    baseline = JSON.stringify(form);
+                    if (creating)
+                        return offerTryAgent(form, models, change.live);
+                    break;
+                }
+                case "cancel": {
+                    if (dirty) {
+                        const discard = await askChoice("Discard unsaved changes?", [
+                            { value: "keep", label: "Keep editing" },
+                            { value: "discard", label: "Discard and close" },
+                        ]);
+                        if (discard === "discard")
+                            return;
+                        break;
+                    }
+                    return;
+                }
+            }
+            show();
+        };
+        show();
+    };
+    /** `/agents new [description]`: assisted (with a description), template or blank. */
+    const newAgentFlow = async (description) => {
+        const models = await loadAgentModels();
+        const blank = emptyAgentForm(app.agentDefinitions.defaultScope, defaultAgentModel(models));
+        let mode = description ? "assisted" : undefined;
+        if (!mode)
+            mode = await askChoice("Agents › New agent", [
+                {
+                    value: "assisted",
+                    label: "✦ Describe it — Alisio writes the agent",
+                    description: "The active model drafts the name, instructions and settings",
+                },
+                { value: "template", label: "From a template…" },
+                { value: "blank", label: "Blank agent" },
+            ]);
+        if (mode === "template")
+            return chooseAgentTemplate();
+        if (mode === "blank")
+            return openAgentEditor(blank, models);
+        if (mode !== "assisted")
+            return;
+        const text = description ??
+            (await askInput({
+                provider: "agent",
+                title: "Agents › New agent",
+                label: "Describe the agent you want",
+                initial: "",
+                placeholder: "e.g. reviews pull requests for security issues",
+                step: 1,
+                steps: 1,
+            }));
+        if (!text?.trim())
+            return;
+        const draft = await buildWithAlisio(text);
+        if (!draft)
+            return;
+        const form = applyDraft(blank, draft);
+        if (formErrors(form).length)
+            return openAgentEditor(form, models);
+        const change = await saveAgentForm(form, models);
+        return offerTryAgent({ ...form, id: change.result.id }, models, change.live);
+    };
+    /** `/agents templates`: pick a template, then customize it (and optionally refine it). */
+    const chooseAgentTemplate = async () => {
+        const models = await loadAgentModels();
+        showPicker(new Picker("Agents › Templates", AGENT_TEMPLATES.map((template) => ({
+            value: template.id,
+            label: template.name,
+            description: template.description,
+        })), (item) => {
+            closePicker();
+            const template = AGENT_TEMPLATES.find((candidate) => candidate.id === item.value);
+            if (template)
+                void openAgentEditor(formFromTemplate(template, app.agentDefinitions.defaultScope, defaultAgentModel(models)), models).catch(error);
+        }, closePicker, true, "Type to search. The template opens in the editor; ✦ Refine with Alisio adapts it to your changes.", (items, filter) => filterAgentRows(items, filter)));
+    };
+    /** `/agents manage`: saved project/global agents → edit, activate, try or delete. */
+    const manageAgents = async () => {
+        const list = await app.agentDefinitions.list();
+        if (!list.length)
+            return notice("No saved agents yet. Create one with /agents new.");
+        showPicker(new Picker("Agents › Saved agents", list.map((a) => ({
+            value: `${a.scope}:${a.id}`,
+            label: `${a.name} [${a.scope === "project" ? "Project" : "Global"}]${a.overridesGlobal ? " overrides global" : ""}${a.overriddenByProject ? " (overridden by project)" : ""}`,
+            description: [a.description, a.model].filter(Boolean).join(" · "),
+        })), (item) => {
+            closePicker();
+            const found = list.find((a) => `${a.scope}:${a.id}` === item.value);
+            if (found)
+                void agentActions(found).catch(error);
+        }, closePicker, true, `Project: ${app.agentDefinitions.scopes.includes("project") ? app.agentDefinitions.dir("project") : "—"} · Global: ${app.agentDefinitions.dir("global")}`, (items, filter) => filterAgentRows(items, filter)));
+    };
+    const agentActions = async (definition) => {
+        const action = await askChoice(`${definition.name} [${definition.scope}]`, [
+            { value: "edit", label: "Edit" },
+            { value: "activate", label: "Activate in this session", description: "From the next prompt" },
+            { value: "try", label: "Try it in a new session" },
+            { value: "delete", label: "Delete", description: definition.path },
+        ]);
+        if (action === "edit") {
+            const form = formFromDefinition(definition);
+            return openAgentEditor(form, await loadAgentModels(), form);
+        }
+        if (action === "try")
+            return tryAgentInNewSession(definition.id);
+        if (action === "activate") {
+            const agent = mainAgents().find((candidate) => candidate.id === definition.id);
+            if (!agent)
+                return notice(`Agent ${definition.id} is not loaded; restart Alisio to use it.`);
+            return applyActiveAgent(agent);
+        }
+        if (action === "delete") {
+            const confirm = await askChoice(`Delete ${definition.path}?`, [
+                { value: "no", label: "Keep it" },
+                { value: "yes", label: "Delete the file" },
+            ]);
+            if (confirm !== "yes")
+                return;
+            const change = await app.agentDefinitions.delete(definition.scope, definition.id);
+            editor.setAutocompleteProvider(buildSlashCompletionProvider());
+            notice(change.live
+                ? `Deleted agent ${definition.name}; it is no longer offered.`
+                : `Deleted ${definition.path}. Restart Alisio to drop it from the running agents.`);
+        }
+    };
+    /** Routes `/agents [verb]`: TUI manager verbs, else the subagents plugin's verbs. */
+    const agentsCommand = async (args, raw) => {
+        const command = parseAgentsArgs(args);
+        if (command.kind === "plugin") {
+            const handler = app.plugins.commands.get("agents");
+            if (!handler)
+                return error("Subagent task management needs the Subagents plugin.");
+            const output = await handler(command.args, { sessionId: session });
+            if (/^reload\b/.test(command.args))
+                editor.setAutocompleteProvider(buildSlashCompletionProvider());
+            return info(output);
+        }
+        if (busy) {
+            editor.setText(raw);
+            flashHint("A turn is running: wait for it to finish before managing agents");
+            return;
+        }
+        switch (command.kind) {
+            case "picker":
+                // Pick up files edited outside Alisio before listing.
+                await app.agentDefinitions.reload();
+                return openAgentsPicker();
+            case "new":
+                return newAgentFlow(command.description);
+            case "templates":
+                return chooseAgentTemplate();
+            case "manage":
+                return manageAgents();
+            case "edit":
+            case "delete": {
+                const list = await app.agentDefinitions.list();
+                const found = list.find((a) => a.id === command.id && (!command.scope || a.scope === command.scope)) ??
+                    undefined;
+                if (!found)
+                    return error(`No saved agent ${command.id}. See /agents manage.`);
+                if (command.kind === "edit") {
+                    const form = formFromDefinition(found);
+                    return openAgentEditor(form, await loadAgentModels(), form);
+                }
+                return agentActions(found);
+            }
+        }
+    };
     /**
      * `/effort [level]`: without an argument, a picker over the ACTIVE model's advertised effort
      * levels (marking the model default); with an argument, the level is validated against
@@ -1537,6 +1975,19 @@ export async function runTui(options) {
                     return error(`Unknown plugin command: ${command ?? ""}`);
                 return info(await handler(rest.join(" ")));
             }
+            const agentId = agentIdFromCommand(parsed.name);
+            if (agentId) {
+                // `/agent:<id>`: activates a loaded agent from the next prompt (as the /agents picker).
+                if (busy) {
+                    editor.setText(raw);
+                    flashHint("A turn is running: wait for it to finish before switching the active agent");
+                    return;
+                }
+                const agent = mainAgents().find((candidate) => candidate.id === agentId);
+                if (!agent)
+                    return error(`Unknown agent ${agentId}. Open /agents to see the loaded agents.`);
+                return applyActiveAgent(agent);
+            }
             switch (name) {
                 case "help":
                     return info(helpReport());
@@ -1586,23 +2037,11 @@ export async function runTui(options) {
                         `(reuse the user's own wording for the question text). Do not answer in plain text ` +
                         `first; call the tool right away.`);
                 }
-                case "agents": {
-                    // The subagents plugin registers its own built-in `/agents` command for subagent task
-                    // management (list/open/cancel/kill/resume/merge/discard/defs). With arguments, route
-                    // to it verbatim (still available while a turn runs, exactly as before); without
-                    // arguments, this opens the ACTIVE-agent picker.
-                    if (parsed.args) {
-                        const handler = app.plugins.commands.get("agents");
-                        if (handler)
-                            return info(await handler(parsed.args, { sessionId: session }));
-                    }
-                    if (busy) {
-                        editor.setText(raw);
-                        flashHint("A turn is running: wait for it to finish before switching the active agent");
-                        return;
-                    }
-                    return openAgentsPicker();
-                }
+                case "agents":
+                    // TUI manager verbs (picker, new, templates, manage, edit, delete); other verbs go to the
+                    // subagents plugin's own `/agents` command (list/open/cancel/kill/resume/merge/discard/
+                    // defs/reload), still available while a turn runs.
+                    return await agentsCommand(parsed.args, raw);
                 case "effort":
                     if (busy) {
                         editor.setText(raw);
@@ -1666,6 +2105,11 @@ export async function runTui(options) {
                 description: c.description ?? `plugin ${c.plugin}`,
                 ...(c.argumentHint ? { argumentHint: c.argumentHint } : {}),
             })),
+            // `/agent:<id>` for every loaded agent (namespaced: never collides with other commands).
+            ...agentCommandDescriptors(mainAgents()).map((d) => ({
+                name: d.name,
+                description: d.description,
+            })),
         ];
         return new CombinedAutocompleteProvider(slashCompletionCommands(sources, {
             sessions: (prefix) => workspaceSessions()

package/dist/tui/connect-input.d.ts

@@ -26,6 +26,8 @@ export declare class ConnectInputPrompt implements Component {
         hint?: string;
         step: number;
         steps: number;
+        /** Dialog title (default `Connect · <provider>`). */
+        title?: string;
         onSubmit: (value: string) => void;
         onCancel: () => void;
     });

package/dist/tui/connect-input.js

@@ -92,7 +92,7 @@ export class ConnectInputPrompt {
         const rule = "─".repeat(Math.max(1, Math.min(56, width - 2)));
         return [
             truncateToWidth(style.cyan(`┌${rule}┐`), width),
-            truncateToWidth(`│ ${style.bold(`Connect · ${this.options.provider}`)} ${style.dim(`(${this.options.step}/${this.options.steps})`)}`, width),
+            truncateToWidth(`│ ${style.bold(this.options.title ?? `Connect · ${this.options.provider}`)}${this.options.title && this.options.steps <= 1 ? "" : ` ${style.dim(`(${this.options.step}/${this.options.steps})`)}`}`, width),
             truncateToWidth(`│ ${style.brightCyan("❯")} ${style.bold(this.options.label)}`, width),
             truncateToWidth(`│   ${field}`, width),
             ...(this.options.hint ? [truncateToWidth(`│   ${style.dim(this.options.hint)}`, width)] : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/alisio-code",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "description": "Alisio: an extensible, provider-agnostic coding-agent harness for your terminal. TUI, OpenAI-compatible providers, permissioned local tools, context compaction, persistent memory and a typed plugin SDK.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -45,12 +45,12 @@
     "alisio": "./dist/main.js"
   },
   "dependencies": {
-    "@alisio/core": "0.1.0-alpha.20",
+    "@alisio/core": "0.1.0-alpha.21",
     "@alisio/plugin-memory": "0.1.0-alpha.9",
     "@alisio/plugin-openai-compatible": "0.1.0-alpha.9",
-    "@alisio/plugin-subagents": "0.1.0-alpha.10",
-    "@alisio/sdk": "0.1.0-alpha.16",
-    "@alisio/server": "0.1.0-alpha.3",
+    "@alisio/plugin-subagents": "0.1.0-alpha.11",
+    "@alisio/sdk": "0.1.0-alpha.17",
+    "@alisio/server": "0.1.0-alpha.5",
     "@earendil-works/pi-tui": "0.87.1",
     "commander": "15.0.0"
   },