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

package/dist/agents/service.js

@@ -0,0 +1,86 @@
+import { AgentNotFoundError, AgentScopeStore, agentScopeDir } from "./definitions.js";
+/** Applies the project-over-global precedence and marks both sides of an override. */
+export function mergeAgentScopes(project, global) {
+    const projectIds = new Set(project.map((a) => a.id));
+    const globalIds = new Set(global.map((a) => a.id));
+    const byName = (a, b) => a.name.localeCompare(b.name) || (a.scope === b.scope ? 0 : a.scope === "project" ? -1 : 1);
+    return [
+        ...project.map((a) => (globalIds.has(a.id) ? { ...a, overridesGlobal: true } : a)),
+        ...global.map((a) => (projectIds.has(a.id) ? { ...a, overriddenByProject: true } : a)),
+    ].sort(byName);
+}
+export class AgentDefinitionService {
+    options;
+    stores = {};
+    constructor(options) {
+        this.options = options;
+        this.stores.global = new AgentScopeStore("global", agentScopeDir("global", options), options.now);
+        if (options.workspace)
+            this.stores.project = new AgentScopeStore("project", agentScopeDir("project", options), options.now);
+    }
+    /** Scopes available here: `project` only with a workspace. */
+    get scopes() {
+        return this.stores.project ? ["project", "global"] : ["global"];
+    }
+    /** The scope new agents default to: the project when a workspace is open. */
+    get defaultScope() {
+        return this.stores.project ? "project" : "global";
+    }
+    dir(scope) {
+        return this.store(scope).dir;
+    }
+    store(scope) {
+        const store = this.stores[scope];
+        if (!store)
+            throw new Error(`The ${scope} scope is not available without a workspace`);
+        return store;
+    }
+    async list() {
+        const [project, global] = await Promise.all([
+            this.stores.project?.list() ?? Promise.resolve([]),
+            this.store("global").list(),
+        ]);
+        return mergeAgentScopes(project, global);
+    }
+    async get(scope, id) {
+        const all = await this.list();
+        return all.find((a) => a.scope === scope && a.id === id);
+    }
+    async create(scope, input) {
+        const created = await this.store(scope).create(input);
+        return this.settle(created.id, scope, created.path, true);
+    }
+    async update(scope, id, input) {
+        const updated = await this.store(scope).update(id, input);
+        return this.settle(updated.id, scope, updated.path, true);
+    }
+    async delete(scope, id) {
+        const store = this.store(scope);
+        const existing = await store.get(id);
+        if (!existing)
+            throw new AgentNotFoundError(scope, id);
+        const deleted = await store.delete(id);
+        const live = (await this.reload()) && !this.isLoaded(existing.path);
+        return { result: deleted, live };
+    }
+    /** Asks the runtime registry to rediscover agent files (false: nothing could reload). */
+    async reload() {
+        if (!this.options.registry)
+            return false;
+        try {
+            return await this.options.registry.reload();
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Whether the runtime registry has `path` loaded (false when unknown). */
+    isLoaded(path) {
+        return !!this.options.registry?.loadedPaths()?.includes(path);
+    }
+    async settle(id, scope, path, mustBeLoaded) {
+        const reloaded = await this.reload();
+        const result = (await this.get(scope, id));
+        return { result, live: reloaded && this.isLoaded(path) === mustBeLoaded };
+    }
+}

package/dist/agents/templates.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Predefined starting points for new agents, shared by the web Agents window (served by
+ * `GET /api/agents/templates`) and the TUI `/agents` manager. A template never chooses a model:
+ * the editor starts from the active one.
+ */
+import type { AgentTemplateInfo } from "@alisio/sdk";
+export declare const AGENT_TEMPLATES: readonly AgentTemplateInfo[];
+export declare function agentTemplate(id: string): AgentTemplateInfo | undefined;

package/dist/agents/templates.js

@@ -0,0 +1,102 @@
+const lines = (...parts) => parts.join("\n");
+export const AGENT_TEMPLATES = [
+    {
+        id: "code-reviewer",
+        name: "Code Reviewer",
+        description: "Reads a diff or a set of files and reports bugs, risky changes and missing tests, ordered by severity.",
+        instructions: lines("You are a meticulous code reviewer working inside the user's repository.", "", "- Start from the change under review (git diff, the files named by the user) and read the surrounding code before judging it.", "- Report correctness bugs first, then security and data-loss risks, then maintainability. Skip pure style nits unless asked.", "- For every finding give the file and line, why it is a problem, and a concrete fix.", "- Say explicitly when you found nothing serious; never invent issues to fill a report.", "- Do not edit files unless the user asks you to apply a fix."),
+        reasoning: { effort: "high", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+    {
+        id: "test-writer",
+        name: "Test Writer",
+        description: "Adds focused tests for existing behavior or a new change, following the project's test framework and conventions.",
+        instructions: lines("You write automated tests for this project.", "", "- Detect the test framework, file layout and helpers already in use and follow them.", "- Test observable behavior at module boundaries; avoid snapshots that only restate the implementation.", "- Cover the happy path, edge cases and failure modes. Keep each test small and named after the behavior it proves.", "- Run the tests you add and report the command and its result. If a test fails because of a real bug, say so instead of weakening the assertion."),
+        reasoning: { effort: "medium", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "low" },
+    },
+    {
+        id: "refactoring-assistant",
+        name: "Refactoring Assistant",
+        description: "Improves the structure of existing code in small, behavior-preserving steps verified by the test suite.",
+        instructions: lines("You refactor code without changing its behavior.", "", "- Before editing, explain the smell you are addressing and the target shape in a few lines.", "- Work in small steps; run the relevant tests after each meaningful step.", "- Keep public interfaces stable unless the user agrees to change them, and update every caller when they do change.", "- Do not mix refactoring with feature work or formatting churn.", "- Finish with a short summary of what moved where and how it was verified."),
+        reasoning: { effort: "high", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+    {
+        id: "documentation-writer",
+        name: "Documentation Writer",
+        description: "Writes and updates READMEs, guides and API docs that match the code as it is today.",
+        instructions: lines("You write clear technical documentation for this project.", "", "- Read the code first; document what it actually does, not what it was meant to do.", "- Lead with the task the reader wants to accomplish, then details. Prefer short sections, lists and runnable examples.", "- Keep commands, flags and configuration keys exact, and keep every translated copy of a page in sync.", "- Flag behavior that looks wrong instead of documenting it as intended."),
+        reasoning: { effort: "low", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+    {
+        id: "security-auditor",
+        name: "Security Auditor",
+        description: "Looks for vulnerabilities such as injection, secret leaks, unsafe defaults and weak access control, with evidence.",
+        instructions: lines("You audit code for security problems.", "", "- Trace untrusted input from where it enters (HTTP, CLI arguments, files, environment) to where it is used.", "- Look for injection, path traversal, unsafe deserialization, missing authorization, secrets in code or logs, and insecure defaults.", "- Rate every finding (critical, high, medium, low) and include the exploit path, the affected code and a fix.", "- Distinguish confirmed issues from hypotheses. Never run destructive commands or exfiltrate data while testing."),
+        reasoning: { effort: "high", summary: "detailed" },
+        text: { format: { type: "text" }, verbosity: "high" },
+    },
+    {
+        id: "debugger",
+        name: "Bug Triage & Debugger",
+        description: "Reproduces a reported failure, isolates the root cause and proposes the smallest safe fix.",
+        instructions: lines("You debug problems reported by the user.", "", "1. Restate the symptom and gather facts: error output, logs, recent changes, versions.", "2. Reproduce it with the smallest possible command or test before changing anything.", "3. Form hypotheses and test them one at a time; record what each experiment ruled out.", "4. Fix the root cause, not the symptom, and add a regression test when the project has tests.", "", "If you cannot reproduce the issue, say what you tried and what information would unblock you."),
+        reasoning: { effort: "high", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+    {
+        id: "migration-assistant",
+        name: "Migration Assistant",
+        description: "Plans and carries out upgrades of frameworks, libraries or APIs across the codebase, one verified batch at a time.",
+        instructions: lines("You migrate this codebase from one version, library or API to another.", "", "- Read the official migration notes for the target version when they are available and list the breaking changes that apply here.", "- Inventory every affected call site before editing, then migrate in batches that keep the build green.", "- Run the type checker and tests after each batch and report anything you had to leave behind.", "- Never silence errors with casts or disabled checks just to finish a batch."),
+        reasoning: { effort: "high", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+    {
+        id: "research-agent",
+        name: "Research Agent",
+        description: "Investigates a question across the web, documentation and local data, and returns a sourced, structured report.",
+        instructions: lines("You are a research assistant.", "", "- Clarify the question and the decision it supports before searching.", "- Gather evidence from several independent sources; prefer primary documentation and data over summaries.", "- Organize the answer as: summary, key findings, evidence (with links or file paths), open questions.", "- Mark uncertainty explicitly and never present a guess as a sourced fact."),
+        reasoning: { effort: "medium", summary: "concise" },
+        text: { format: { type: "text" }, verbosity: "high" },
+    },
+    {
+        id: "customer-support-agent",
+        name: "Customer Support Agent",
+        description: "Answers customer requests politely, checks the account details it is given and hands off what it cannot resolve.",
+        instructions: lines("You help customers resolve their requests.", "", "- Be warm, concise and specific. Confirm what the customer is asking before acting.", "- Use only the account information and tools you are given; never guess balances, orders or personal data.", "- Follow the documented policies. When a request needs a human (refunds above policy, legal or safety issues, angry escalations), say so and summarize the case for the hand-off.", "- End each reply with the next step for the customer."),
+        reasoning: { effort: "low", summary: "none" },
+        text: { format: { type: "text" }, verbosity: "low" },
+    },
+    {
+        id: "devops-assistant",
+        name: "DevOps Assistant",
+        description: "Helps with deployments, CI pipelines, incident response and infrastructure troubleshooting.",
+        instructions: lines("You are a DevOps and site-reliability assistant.", "", "- During an incident, focus on impact and mitigation first, then root cause.", "- Read configuration, pipeline definitions and logs before proposing changes; quote the lines that matter.", "- Prefer reversible, incremental changes. Spell out the exact commands and how to roll them back.", "- Ask before running anything that touches production, deletes resources or rotates credentials."),
+        reasoning: { effort: "medium", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+    {
+        id: "meeting-assistant",
+        name: "Meeting Assistant",
+        description: "Turns meeting transcripts or notes into decisions, action items with owners and a short summary.",
+        instructions: lines("You process meeting transcripts and notes.", "", "Produce, in this order:", "1. A summary of three to five sentences.", "2. Decisions made.", "3. Action items as `owner — task — due date` (write `unassigned` or `no date` when missing).", "4. Open questions and risks.", "", "Use only what the transcript says; do not invent owners or dates."),
+        reasoning: { effort: "low", summary: "none" },
+        text: { format: { type: "text" }, verbosity: "low" },
+    },
+    {
+        id: "analytics-agent",
+        name: "Analytics Agent",
+        description: "Queries data, builds reports and explains trends and anomalies in plain language.",
+        instructions: lines("You are a data analyst.", "", "- Confirm the metric definitions, filters and time range before querying.", "- Show the query or computation you used so the result can be reproduced.", "- Explain what changed, by how much, and the most likely drivers; separate correlation from causation.", "- Call out data quality problems (gaps, duplicates, outliers) instead of hiding them."),
+        reasoning: { effort: "medium", summary: "auto" },
+        text: { format: { type: "text" }, verbosity: "medium" },
+    },
+];
+export function agentTemplate(id) {
+    return AGENT_TEMPLATES.find((template) => template.id === id);
+}

package/dist/application.d.ts

@@ -1,4 +1,5 @@
 import type { AvailableProviderModel, ModelInfo, ModelProvider, Plugin, PluginCategory, ProviderConfigurationValue, ResolvedProviderModel, RunEvent } from "@alisio/sdk";
+import { AgentDefinitionService } from "./agents/service.ts";
 import { type SettableSettingKey } from "./config.ts";
 import type { ApprovalHandler } from "./core/contracts.ts";
 import { ToolRegistry } from "./core/registry.ts";
@@ -212,6 +213,12 @@ export declare function createApplication(options?: AppOptions): Promise<{
     runner: AgentRunner;
     /** `/btw` side questions: tool-less answers about a session outside its conversation. */
     sideQuestions: SideQuestions;
+    /**
+     * User agent files (`<workspace>/.agents/agents`, `~/.agents/agents`). Every write asks the
+     * subagents plugin (the runtime agent registry) to rediscover through its `/agents reload`
+     * verb and reports whether the saved file is loaded; without the plugin nothing reloads.
+     */
+    agentDefinitions: AgentDefinitionService;
     herdr: HerdrBridge;
     contextWindow: (model: string) => number | undefined;
     /** Effective context budget + compaction point shared by the runner and the TUI bar. */

package/dist/application.js

@@ -1,6 +1,7 @@
 import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { AgentDefinitionService } from "./agents/service.js";
 import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
 import { completeText } from "./core/compaction.js";
 import { ToolRegistry } from "./core/registry.js";
@@ -862,6 +863,38 @@ export async function createApplication(options = {}) {
             runner,
             /** `/btw` side questions: tool-less answers about a session outside its conversation. */
             sideQuestions: new SideQuestions({ runner, state: store }),
+            /**
+             * User agent files (`<workspace>/.agents/agents`, `~/.agents/agents`). Every write asks the
+             * subagents plugin (the runtime agent registry) to rediscover through its `/agents reload`
+             * verb and reports whether the saved file is loaded; without the plugin nothing reloads.
+             */
+            agentDefinitions: new AgentDefinitionService({
+                workspace,
+                home: homedir(),
+                registry: {
+                    async reload() {
+                        const handler = plugins.commands.get("agents");
+                        if (!handler)
+                            return false;
+                        await handler("reload");
+                        return Array.isArray(plugins.pluginState("subagents", "definitions"));
+                    },
+                    loadedPaths() {
+                        let state;
+                        try {
+                            state = plugins.pluginState("subagents", "definitions");
+                        }
+                        catch {
+                            return undefined;
+                        }
+                        if (!Array.isArray(state))
+                            return undefined;
+                        return state
+                            .map((entry) => entry?.path)
+                            .filter((path) => typeof path === "string");
+                    },
+                },
+            }),
             herdr,
             contextWindow,
             /** Effective context budget + compaction point shared by the runner and the TUI bar. */

package/dist/commands/catalog.js

@@ -1,4 +1,4 @@
-import { agentCatalogFromState, resolveActiveAgent } from "../agents/active.js";
+import { agentCatalogFromState, agentCommandDescriptors, resolveActiveAgent, } from "../agents/active.js";
 import { formatSideQuestion, SIDE_QUESTION_DESCRIPTION, SIDE_QUESTION_USAGE, } from "../sessions/side-questions.js";
 import { BUILTIN_COMMANDS } from "./builtins.js";
 export { BUILTIN_COMMANDS };
@@ -259,6 +259,18 @@ export class CommandCatalog {
                     surfaces: [...ALL],
                     execution: "surface",
                 });
+        // `/agent:<id>` activates a loaded agent (built-ins, project and global agent files).
+        if (host?.plugins) {
+            let state;
+            try {
+                state = host.plugins.pluginState?.("subagents", "mainAgents");
+            }
+            catch {
+                /* agent contributions are best-effort */
+            }
+            for (const descriptor of agentCommandDescriptors(agentCatalogFromState(state), taken))
+                push(descriptor);
+        }
         return surface ? out.filter((c) => c.surfaces.includes(surface)) : out;
     }
     /** A command by name or alias (built-in names and aliases are case-insensitive). */

package/dist/index.d.ts

@@ -1,6 +1,12 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
-export { type ActiveAgent, type AgentPickerItem, activeAgentCatalog, agentCatalogFromState, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, DEFAULT_AGENT_ID, type MainCapableAgentRecord, mainAgentFromRecord, resolveActiveAgent, } from "./agents/active.ts";
+export { type ActiveAgent, AGENT_COMMAND_PREFIX, type AgentPickerItem, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, DEFAULT_AGENT_ID, type MainCapableAgentRecord, mainAgentFromRecord, resolveActiveAgent, } from "./agents/active.ts";
+export { agentModelCapabilities, agentModelLabels, agentModelOptions, DEFAULT_EFFORT_LEVELS, fitAgentSettings, } from "./agents/capabilities.ts";
+export { AGENT_AUTHORING_SKILL_NAMES, CREATE_AGENT_SKILL, } from "./agents/create-agent-skill.ts";
+export { AGENT_ID_PATTERN, AGENT_LIMITS, AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, type AgentFieldError, AgentNotFoundError, AgentScopeStore, agentIdFromName, agentScopeDir, parseAgentFile, RESERVED_AGENT_IDS, slugify, validateAgentDefinitionInput, } from "./agents/definitions.ts";
+export { AGENT_DRAFT_INSTRUCTIONS, AGENT_DRAFT_MAX_DESCRIPTION, type AgentAuthoringGuidance, agentAuthoringGuidance, agentDraftRequest, generateAgentDraft, parseAgentDraft, } from "./agents/draft.ts";
+export { type AgentChange, AgentDefinitionService, type AgentDefinitionServiceOptions, type AgentRegistry, mergeAgentScopes, } from "./agents/service.ts";
+export { AGENT_TEMPLATES, agentTemplate } from "./agents/templates.ts";
 export { type AppOptions, type BuiltinContext, type BuiltinPlugin, createApplication, enabledBuiltins, type PluginCatalogEntry, type PluginCatalogStatus, } from "./application.ts";
 export { BUILTIN_COMMANDS, type BuiltinCommand, CommandCatalog, type CommandExecutionContext, type CommandHost, type CommandResult, type CommandSurface, } from "./commands/catalog.ts";
 export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, isSettableSettingKey, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, overridesSavedProviderProfile, type SettableSettingInfo, type SettableSettingKey, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.ts";

package/dist/index.js

@@ -1,6 +1,12 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
-export { activeAgentCatalog, agentCatalogFromState, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, DEFAULT_AGENT_ID, mainAgentFromRecord, resolveActiveAgent, } from "./agents/active.js";
+export { AGENT_COMMAND_PREFIX, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, DEFAULT_AGENT_ID, mainAgentFromRecord, resolveActiveAgent, } from "./agents/active.js";
+export { agentModelCapabilities, agentModelLabels, agentModelOptions, DEFAULT_EFFORT_LEVELS, fitAgentSettings, } from "./agents/capabilities.js";
+export { AGENT_AUTHORING_SKILL_NAMES, CREATE_AGENT_SKILL, } from "./agents/create-agent-skill.js";
+export { AGENT_ID_PATTERN, AGENT_LIMITS, AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, AgentNotFoundError, AgentScopeStore, agentIdFromName, agentScopeDir, parseAgentFile, RESERVED_AGENT_IDS, slugify, validateAgentDefinitionInput, } from "./agents/definitions.js";
+export { AGENT_DRAFT_INSTRUCTIONS, AGENT_DRAFT_MAX_DESCRIPTION, agentAuthoringGuidance, agentDraftRequest, generateAgentDraft, parseAgentDraft, } from "./agents/draft.js";
+export { AgentDefinitionService, mergeAgentScopes, } from "./agents/service.js";
+export { AGENT_TEMPLATES, agentTemplate } from "./agents/templates.js";
 export { createApplication, enabledBuiltins, } from "./application.js";
 export { BUILTIN_COMMANDS, CommandCatalog, } from "./commands/catalog.js";
 export { configFile, configHome, configSchema, isSettableSettingKey, loadConfig, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.1.0-alpha.16",
+    "@alisio/sdk": "0.1.0-alpha.17",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",