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

package/dist/agents/active.d.ts

@@ -9,6 +9,7 @@
  * agent only when it is marked main-capable (`mode: primary|all`), which the subagents plugin
  * publishes for the host to read.
  */
+import type { CommandDescriptor } from "@alisio/sdk";
 export interface ActiveAgent {
     /** Stable id, also the persisted `agents.active` value. */
     id: string;
@@ -20,6 +21,10 @@ export interface ActiveAgent {
     model?: string;
     /** Read-only agents run with write/process/external tools disabled and approvals off. */
     readOnly?: boolean;
+    /** Default reasoning effort (`alisio.reasoning.effort`); an explicit session/user effort wins. */
+    effort?: string;
+    /** Definition file of a contributed agent (shows its Project/Global scope). */
+    path?: string;
     /** Product built-ins are shown as built-in and never shadowed by contributed definitions. */
     source: "builtin" | "user" | "plugin";
 }
@@ -32,6 +37,7 @@ export interface MainCapableAgentRecord {
     prompt: string;
     model?: string;
     readOnly?: boolean;
+    effort?: string;
     source: string;
     path?: string;
 }
@@ -56,7 +62,20 @@ export declare function agentRunOptions(agent: ActiveAgent | undefined): {
         external: false;
     };
     approvals?: false;
+    reasoningEffort?: string;
 };
+/**
+ * Every loaded agent is also a slash command `/agent:<id>` that activates it. The `agent:`
+ * namespace keeps these commands from ever colliding with built-ins, plugin commands, prompt
+ * templates or `skill:<id>` entries; when a higher-precedence source already owns the exact name
+ * (e.g. a plugin with id `agent`), the agent command is skipped.
+ */
+export declare const AGENT_COMMAND_PREFIX = "agent:";
+export declare const agentCommandName: (id: string) => string;
+/** The agent id a `/agent:<id>` command names, or undefined for any other command. */
+export declare function agentIdFromCommand(name: string): string | undefined;
+/** `/agent:<id>` descriptors for `agents`, skipping names already in `taken`. */
+export declare function agentCommandDescriptors(agents: ActiveAgent[], taken?: ReadonlySet<string>): CommandDescriptor[];
 export interface AgentPickerItem {
     value: string;
     label: string;

package/dist/agents/active.js

@@ -36,6 +36,8 @@ export function mainAgentFromRecord(record) {
         ...(record.prompt ? { instructions: record.prompt } : {}),
         ...(record.model ? { model: record.model } : {}),
         ...(record.readOnly ? { readOnly: true } : {}),
+        ...(typeof record.effort === "string" && record.effort ? { effort: record.effort } : {}),
+        ...(typeof record.path === "string" && record.path ? { path: record.path } : {}),
         ...(source.startsWith("plugin:")
             ? { source: "plugin" }
             : { source: "user" }),
@@ -82,6 +84,7 @@ export function agentRunOptions(agent) {
         return {};
     return {
         ...(agent.instructions ? { instructions: agent.instructions } : {}),
+        ...(agent.effort ? { reasoningEffort: agent.effort } : {}),
         ...(agent.readOnly
             ? {
                 policy: { write: false, process: false, external: false },
@@ -90,6 +93,44 @@ export function agentRunOptions(agent) {
             : {}),
     };
 }
+/**
+ * Every loaded agent is also a slash command `/agent:<id>` that activates it. The `agent:`
+ * namespace keeps these commands from ever colliding with built-ins, plugin commands, prompt
+ * templates or `skill:<id>` entries; when a higher-precedence source already owns the exact name
+ * (e.g. a plugin with id `agent`), the agent command is skipped.
+ */
+export const AGENT_COMMAND_PREFIX = "agent:";
+const COMMAND_SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+export const agentCommandName = (id) => `${AGENT_COMMAND_PREFIX}${id}`;
+/** The agent id a `/agent:<id>` command names, or undefined for any other command. */
+export function agentIdFromCommand(name) {
+    if (!name.startsWith(AGENT_COMMAND_PREFIX))
+        return undefined;
+    const id = name.slice(AGENT_COMMAND_PREFIX.length);
+    return COMMAND_SAFE_ID.test(id) ? id : undefined;
+}
+/** `/agent:<id>` descriptors for `agents`, skipping names already in `taken`. */
+export function agentCommandDescriptors(agents, taken = new Set()) {
+    const out = [];
+    const seen = new Set(taken);
+    for (const agent of agents) {
+        if (!COMMAND_SAFE_ID.test(agent.id))
+            continue;
+        const name = agentCommandName(agent.id);
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        out.push({
+            name,
+            description: `Activate the ${agent.name} agent${agent.id === DEFAULT_AGENT_ID ? " (default)" : ""}: ${agent.description}`,
+            source: "agent",
+            owner: agent.source,
+            surfaces: ["tui", "web", "api"],
+            execution: "surface",
+        });
+    }
+    return out;
+}
 /** Picker rows for `/agents`: name with (current), built-in/default and read-only markers. */
 export function agentPickerItems(agents, activeId) {
     return agents.map((agent) => ({

package/dist/agents/capabilities.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Capability-driven agent settings: which reasoning, summary, verbosity and text-format options a
+ * model supports, derived only from its catalog metadata (`ModelInfo.effort`, `inputModalities`,
+ * `capabilities`). Providers that declare nothing (most OpenAI-compatible `GET /models` answers)
+ * get a permissive default: every option is offered and `known` is false, so surfaces can say the
+ * support is unverified. Explicit `false` metadata always hides an option.
+ */
+import type { AgentDefinitionInput, AgentModelCapabilities, AgentModelOption, AvailableProviderModel, ModelInfo } from "@alisio/sdk";
+/** Levels offered when a reasoning model does not list its own. */
+export declare const DEFAULT_EFFORT_LEVELS: string[];
+/** What `model` supports for the agent editor (permissive when the catalog says nothing). */
+export declare function agentModelCapabilities(model: ModelInfo | undefined): AgentModelCapabilities;
+/** Short labels such as "Reasoning · Tools · Vision", only for declared support. */
+export declare function agentModelLabels(capabilities: AgentModelCapabilities): string[];
+/** The editor's model options from the configured catalogs; `active` marks the running model. */
+export declare function agentModelOptions(available: AvailableProviderModel[], active?: {
+    profile?: string;
+    provider?: string;
+    model: string;
+}): AgentModelOption[];
+/**
+ * Drops or replaces settings `capabilities` does not support: unsupported reasoning settings are
+ * removed, an unknown effort level falls back to the model default (or is removed), an unsupported
+ * text format becomes `text`, unsupported verbosity is removed.
+ */
+export declare function fitAgentSettings<T extends Pick<AgentDefinitionInput, "reasoning" | "text">>(settings: T, capabilities: AgentModelCapabilities): T;

package/dist/agents/capabilities.js

@@ -0,0 +1,120 @@
+/** Levels offered when a reasoning model does not list its own. */
+export const DEFAULT_EFFORT_LEVELS = ["low", "medium", "high"];
+const flag = (capabilities, keys) => {
+    if (!capabilities)
+        return undefined;
+    for (const key of keys) {
+        const value = capabilities[key];
+        if (typeof value === "boolean")
+            return value;
+        if (value === "true" || value === "supported")
+            return true;
+        if (value === "false" || value === "unsupported")
+            return false;
+    }
+    return undefined;
+};
+/** What `model` supports for the agent editor (permissive when the catalog says nothing). */
+export function agentModelCapabilities(model) {
+    const caps = model?.capabilities;
+    const levels = model?.effort?.supportedLevels?.filter(Boolean) ?? [];
+    const declaredReasoning = flag(caps, ["reasoning", "reasoning_effort", "thinking"]);
+    const reasoning = levels.length > 0 || declaredReasoning !== false;
+    const summary = reasoning && flag(caps, ["reasoning_summary", "reasoningSummary"]) !== false;
+    const verbosity = flag(caps, ["verbosity", "text_verbosity"]) !== false;
+    const json = flag(caps, ["json_mode", "json_object", "response_format"]);
+    const schema = flag(caps, ["structured_outputs", "json_schema", "structuredOutputs"]);
+    const textFormats = ["text"];
+    if (json !== false)
+        textFormats.push("json_object");
+    if (schema !== false)
+        textFormats.push("json_schema");
+    const tools = flag(caps, ["tools", "tool_calling", "function_calling", "toolCalling"]);
+    const vision = model?.inputModalities?.includes("image") ||
+        model?.modalities?.includes("image") ||
+        flag(caps, ["vision", "image_input"]) === true
+        ? true
+        : flag(caps, ["vision", "image_input"]);
+    const known = !!levels.length ||
+        !!model?.inputModalities?.length ||
+        !!model?.modalities?.length ||
+        !!(caps && Object.keys(caps).length);
+    return {
+        known,
+        reasoning,
+        effortLevels: reasoning ? (levels.length ? levels : DEFAULT_EFFORT_LEVELS) : [],
+        ...(reasoning && model?.effort?.defaultLevel
+            ? { defaultEffort: model.effort.defaultLevel }
+            : {}),
+        summary,
+        verbosity,
+        textFormats,
+        ...(tools !== undefined ? { tools } : {}),
+        ...(vision !== undefined ? { vision } : {}),
+    };
+}
+/** Short labels such as "Reasoning · Tools · Vision", only for declared support. */
+export function agentModelLabels(capabilities) {
+    if (!capabilities.known)
+        return [];
+    return [
+        capabilities.reasoning ? "Reasoning" : undefined,
+        capabilities.tools ? "Tools" : undefined,
+        capabilities.vision ? "Vision" : undefined,
+        capabilities.textFormats.includes("json_schema") ? "Structured output" : undefined,
+    ].filter((label) => !!label);
+}
+/** The editor's model options from the configured catalogs; `active` marks the running model. */
+export function agentModelOptions(available, active) {
+    return available.map((entry) => {
+        const capabilities = agentModelCapabilities(entry.model);
+        return {
+            reference: entry.reference,
+            provider: entry.provider,
+            profile: entry.profile,
+            providerName: entry.providerName,
+            id: entry.model.id,
+            ...(entry.model.name ? { name: entry.model.name } : {}),
+            active: !!active &&
+                entry.model.id === active.model &&
+                (active.profile ? entry.profile === active.profile : entry.provider === active.provider),
+            capabilities,
+            labels: agentModelLabels(capabilities),
+        };
+    });
+}
+/**
+ * Drops or replaces settings `capabilities` does not support: unsupported reasoning settings are
+ * removed, an unknown effort level falls back to the model default (or is removed), an unsupported
+ * text format becomes `text`, unsupported verbosity is removed.
+ */
+export function fitAgentSettings(settings, capabilities) {
+    const reasoning = { ...(settings.reasoning ?? {}) };
+    if (!capabilities.reasoning) {
+        delete reasoning.effort;
+        delete reasoning.summary;
+    }
+    else if (reasoning.effort && !capabilities.effortLevels.includes(reasoning.effort)) {
+        if (capabilities.defaultEffort)
+            reasoning.effort = capabilities.defaultEffort;
+        else
+            delete reasoning.effort;
+    }
+    if (!capabilities.summary)
+        delete reasoning.summary;
+    const text = { ...(settings.text ?? {}) };
+    if (text.format && !capabilities.textFormats.includes(text.format.type))
+        text.format = { type: "text" };
+    if (!capabilities.verbosity)
+        delete text.verbosity;
+    const out = { ...settings };
+    if (Object.keys(reasoning).length)
+        out.reasoning = reasoning;
+    else
+        delete out.reasoning;
+    if (Object.keys(text).length)
+        out.text = text;
+    else
+        delete out.text;
+    return out;
+}

package/dist/agents/create-agent-skill.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The bundled `create-agent` skill: agent-authoring standards the ACTIVE model follows when it
+ * writes or refines an agent's instructions (assisted creation in the web Agents window and the
+ * TUI `/agents` manager). A user or project skill named `create-agent` (or `agent-creator`)
+ * replaces it, so teams can encode their own conventions.
+ */
+/** Skill names that override the bundled guidance, in order of preference. */
+export declare const AGENT_AUTHORING_SKILL_NAMES: readonly ["create-agent", "agent-creator"];
+export declare const CREATE_AGENT_SKILL = "---\nname: create-agent\ndescription: Standards for writing the system prompt (instructions) of an Alisio agent.\n---\n# Writing agent instructions\n\nAn agent's instructions are its system prompt. They are read on every turn, so every line must\nearn its place. Write them in Markdown, in the second person (\"You ...\"), in English unless the\nuser asks otherwise.\n\n## Required sections\n\n1. **Role** \u2014 one or two sentences: who the agent is and who it serves.\n2. **Goal** \u2014 the outcome a successful turn produces, stated so it can be checked.\n3. **Scope** \u2014 what the agent handles and, explicitly, what it must decline or hand back.\n4. **How to work** \u2014 an ordered method for the typical task (investigate, act, verify, report).\n5. **Tool usage** \u2014 when to read, search, edit or run processes; prefer reading before editing;\n   verify changes (tests, type checks) before claiming success; ask before destructive,\n   irreversible or external actions (deleting data, deploying, spending money, contacting people).\n6. **Constraints** \u2014 hard rules: safety, privacy, secrets never echoed, repository conventions,\n   performance or style limits. Phrase them as testable rules, not vague values.\n7. **Output format** \u2014 the exact shape of the final answer (headings, lists, tables, JSON keys,\n   length). Match the agent's text format setting.\n8. **Examples** (optional) \u2014 one short input \u2192 output pair when the format or tone is unusual.\n\n## Quality bar\n\n- Be specific to the described job; remove generic filler (\"be helpful\", \"be accurate\").\n- Prefer short imperative bullets over paragraphs. Target 150\u2013600 words.\n- Never invent tools, files, APIs or data the agent does not have; tell it to say when it lacks\n  information instead of guessing.\n- Keep the agent honest: report what was verified and what was not.\n- When refining an existing definition, keep what already works, apply the user's requested\n  changes, and fill any missing required section.\n\n## Settings to suggest\n\n- Reasoning effort: `high` for analysis, debugging, security or multi-step refactors; `medium`\n  for general engineering; `low` for formatting, summaries and support replies.\n- Reasoning summary: `auto` by default; `none` for short conversational agents; `detailed` when\n  the user audits the reasoning.\n- Verbosity: `low` for terse operational agents, `medium` by default, `high` for reports.\n- Text format: `text` unless the agent must return machine-readable output (`json_object`,\n  or `json_schema` when a strict schema is given).\n";
+/** The skill body without the loader preamble and frontmatter (what is sent as guidance). */
+export declare function skillBody(text: string): string;

package/dist/agents/create-agent-skill.js

@@ -0,0 +1,60 @@
+/**
+ * The bundled `create-agent` skill: agent-authoring standards the ACTIVE model follows when it
+ * writes or refines an agent's instructions (assisted creation in the web Agents window and the
+ * TUI `/agents` manager). A user or project skill named `create-agent` (or `agent-creator`)
+ * replaces it, so teams can encode their own conventions.
+ */
+/** Skill names that override the bundled guidance, in order of preference. */
+export const AGENT_AUTHORING_SKILL_NAMES = ["create-agent", "agent-creator"];
+export const CREATE_AGENT_SKILL = `---
+name: create-agent
+description: Standards for writing the system prompt (instructions) of an Alisio agent.
+---
+# Writing agent instructions
+
+An agent's instructions are its system prompt. They are read on every turn, so every line must
+earn its place. Write them in Markdown, in the second person ("You ..."), in English unless the
+user asks otherwise.
+
+## Required sections
+
+1. **Role** — one or two sentences: who the agent is and who it serves.
+2. **Goal** — the outcome a successful turn produces, stated so it can be checked.
+3. **Scope** — what the agent handles and, explicitly, what it must decline or hand back.
+4. **How to work** — an ordered method for the typical task (investigate, act, verify, report).
+5. **Tool usage** — when to read, search, edit or run processes; prefer reading before editing;
+   verify changes (tests, type checks) before claiming success; ask before destructive,
+   irreversible or external actions (deleting data, deploying, spending money, contacting people).
+6. **Constraints** — hard rules: safety, privacy, secrets never echoed, repository conventions,
+   performance or style limits. Phrase them as testable rules, not vague values.
+7. **Output format** — the exact shape of the final answer (headings, lists, tables, JSON keys,
+   length). Match the agent's text format setting.
+8. **Examples** (optional) — one short input → output pair when the format or tone is unusual.
+
+## Quality bar
+
+- Be specific to the described job; remove generic filler ("be helpful", "be accurate").
+- Prefer short imperative bullets over paragraphs. Target 150–600 words.
+- Never invent tools, files, APIs or data the agent does not have; tell it to say when it lacks
+  information instead of guessing.
+- Keep the agent honest: report what was verified and what was not.
+- When refining an existing definition, keep what already works, apply the user's requested
+  changes, and fill any missing required section.
+
+## Settings to suggest
+
+- Reasoning effort: \`high\` for analysis, debugging, security or multi-step refactors; \`medium\`
+  for general engineering; \`low\` for formatting, summaries and support replies.
+- Reasoning summary: \`auto\` by default; \`none\` for short conversational agents; \`detailed\` when
+  the user audits the reasoning.
+- Verbosity: \`low\` for terse operational agents, \`medium\` by default, \`high\` for reports.
+- Text format: \`text\` unless the agent must return machine-readable output (\`json_object\`,
+  or \`json_schema\` when a strict schema is given).
+`;
+/** The skill body without the loader preamble and frontmatter (what is sent as guidance). */
+export function skillBody(text) {
+    return text
+        .replace(/^Skill root:.*\r?\n(?:Use skill_resource.*\r?\n)?/, "")
+        .replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "")
+        .trim();
+}

package/dist/agents/definitions.d.ts

@@ -0,0 +1,88 @@
+import type { AgentDefinitionInfo, AgentDefinitionInput, AgentReasoningSummary, AgentScope, AgentTextFormatType, AgentVerbosity } from "@alisio/sdk";
+import { Document } from "yaml";
+export type { AgentDefinitionInfo, AgentDefinitionInput, AgentScope };
+/** Same identifier rule as the subagents plugin (and Claude Code agent names). */
+export declare const AGENT_ID_PATTERN: RegExp;
+/** Built-in agent names a user file must not shadow (main `build`/`plan`, subagents). */
+export declare const RESERVED_AGENT_IDS: Set<string>;
+export declare const AGENT_LIMITS: {
+    readonly name: 80;
+    readonly description: 300;
+    readonly instructions: 24000;
+    readonly model: 300;
+};
+export declare const AGENT_REASONING_SUMMARIES: AgentReasoningSummary[];
+export declare const AGENT_VERBOSITIES: AgentVerbosity[];
+export declare const AGENT_TEXT_FORMATS: AgentTextFormatType[];
+/** Frontmatter key of the Alisio-only settings (ignored by other harnesses). */
+export declare const ALISIO_KEY = "alisio";
+/** The directory of one scope. */
+export declare function agentScopeDir(scope: AgentScope, roots: {
+    workspace?: string;
+    home: string;
+}): string;
+export interface AgentFieldError {
+    field: string;
+    message: string;
+}
+/**
+ * Validates and normalizes an untrusted definition body (web API, TUI, drafts). Unknown keys are
+ * dropped; strings are trimmed; empty optional settings are omitted.
+ */
+export declare function validateAgentDefinitionInput(raw: unknown): {
+    ok: true;
+    value: AgentDefinitionInput;
+} | {
+    ok: false;
+    errors: AgentFieldError[];
+};
+/** Lowercase ASCII slug of a display name (diacritics folded), possibly empty. */
+export declare function slugify(name: string): string;
+/** A fresh id for `name`: its slug, suffixed (`-2`, `-3`…) past reserved and `taken` ids. */
+export declare function agentIdFromName(name: string, taken: Set<string>): string;
+/** The description written when none is given: the first sentence of the instructions. */
+export declare function defaultDescription(name: string, instructions: string): string;
+/** Splits a Markdown agent file into its YAML document and body (no frontmatter: empty doc). */
+export declare function parseAgentFile(text: string): {
+    doc: Document;
+    body: string;
+} | undefined;
+/** The definition a parsed file describes (`id`/`scope`/`path` come from its location). */
+export declare function definitionFromFile(parsed: {
+    doc: Document;
+    body: string;
+}, meta: {
+    id: string;
+    scope: AgentScope;
+    path: string;
+    mtimeMs: number;
+    birthtimeMs?: number;
+}): AgentDefinitionInfo;
+/**
+ * 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 declare function renderAgentFile(doc: Document, id: string, input: AgentDefinitionInput, times: {
+    createdAt: number;
+    updatedAt: number;
+    created: boolean;
+}): string;
+export declare class AgentNotFoundError extends Error {
+    constructor(scope: AgentScope, id: string);
+}
+/** Reads and writes the agent files of one scope directory. */
+export declare class AgentScopeStore {
+    readonly scope: AgentScope;
+    readonly dir: string;
+    private readonly now;
+    constructor(scope: AgentScope, dir: string, now?: () => number);
+    private pathOf;
+    private read;
+    /** Every readable `<id>.md` of the scope (invalid names and unparseable files are skipped). */
+    list(): Promise<AgentDefinitionInfo[]>;
+    get(id: string): Promise<AgentDefinitionInfo | undefined>;
+    create(input: AgentDefinitionInput, extraTaken?: Iterable<string>): Promise<AgentDefinitionInfo>;
+    update(id: string, input: AgentDefinitionInput): Promise<AgentDefinitionInfo>;
+    delete(id: string): Promise<boolean>;
+    private write;
+}