@mushinjs/plugin-agent 0.0.0-stage → 0.2.0-next.20261112165327

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Setobox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+import { SYSTEM_PROMPT, SceneInfo, TurnContext, contextNote, skillBlock } from "./prompt.js";
+import { AgentSettings, CustomRecommendation, SCENE_KEYS, SceneProfile, TokenUsage, ToolPolicy, defaultPolicy, formatSkillMarkdown, parseSkillMarkdown, policyInput, profileInput, today } from "./settings.js";
+import { AgentSkill, BUILTIN_SKILLS, SkillDefinition, SkillSource, skillFields, skillInput } from "./skills.js";
+import { Context, Service, z } from "@mushinjs/core";
+import { LlmMessage, ToolDefinition } from "@mushinjs/plugin-providers";
+declare module '@mushinjs/core' {
+  interface Context {
+    agent: Agent;
+  }
+  interface Events {
+    'agent/event'(event: AgentEvent): void;
+    /** Skills, page profiles or tool policies changed. */
+    'agent/changed'(): void;
+  }
+}
+export type AgentEvent = {
+  session: string;
+} & ({
+  type: 'start';
+} | {
+  type: 'delta';
+  text: string;
+} | {
+  type: 'tool-call';
+  id: string;
+  action: string;
+  input: unknown;
+  risk: string;
+} | {
+  type: 'confirm';
+  id: string;
+  action: string;
+  input: unknown;
+} | {
+  type: 'tool-result';
+  id: string;
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+} | {
+  type: 'done';
+  text: string;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+} |
+/** `code` is `max_steps` when the turn ran out of tool rounds, so the dashboard can offer to go on. */
+{
+  type: 'error';
+  error: string;
+  code?: 'max_steps';
+});
+/**
+ * A stored message; `display` holds the user's own words when the content carries a context note,
+ * and `skills` the names of the skills picked for it.
+ */
+export type AgentMessage = LlmMessage & {
+  display?: string;
+  skills?: string[];
+  /** A chat quoted into the message, as the dashboard shows it: who said what, and where. */
+  quote?: QuotedChat;
+  at: number;
+};
+/** Messages of a bot's chat quoted into an Agent message, around one picked message. */
+export interface QuotedChat {
+  bot: string;
+  botName: string;
+  channel: {
+    type: 'group' | 'private';
+    id: string;
+    name?: string;
+  };
+  /** The picked message's record id; a sample for flows.test and flows.preview. */
+  focus: string;
+  lines: {
+    id: string;
+    direction: 'in' | 'out';
+    user: string;
+    userId: string;
+    text: string;
+    at: number;
+  }[];
+}
+/** Where a conversation was started, for the history list. */
+export interface SessionScene {
+  key: string;
+  label?: string;
+  page?: string;
+}
+export interface AgentSession {
+  id: string;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+  /** Tool list frozen at creation, so every request in the session sends identical tools. */
+  tools: ToolDefinition[];
+  messages: AgentMessage[];
+  /** The page the conversation was started on. */
+  scene?: SessionScene;
+  /** What it touched, for search: `scene:<key>`, `skill:<id>`, `command:<name>`, `resource:<kind>:<id>`. */
+  tags?: string[];
+}
+export interface SendOptions {
+  /** Dashboard connection id; client actions such as ui.navigate are routed back to it. */
+  client?: string;
+  page?: string;
+  /** The page as the dashboard describes it; its hint and state go into the context note. */
+  scene?: SceneInfo;
+  /** Ids of skills whose instructions go into this message. */
+  skills?: string[];
+  /** A message of a bot's chat to quote, with a few messages around it. */
+  quote?: {
+    bot: string;
+    channel: string;
+    id: string;
+    before?: number;
+    after?: number;
+  };
+}
+/** Commands the dashboard runs itself, without asking the model. */
+export declare const BUILTIN_COMMANDS: {
+  name: string;
+  description: string;
+  'zh-CN': string;
+}[];
+export declare const Config: z.ZodObject<{
+  provider: z.ZodOptional<z.ZodString>;
+  model: z.ZodOptional<z.ZodString>;
+  maxSteps: z.ZodDefault<z.ZodNumber>;
+  confirmTimeout: z.ZodDefault<z.ZodNumber>;
+  dailyTokens: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof Config>;
+/** Runs conversations in which the LLM operates Mushin.js through the action registry. */
+export declare class Agent extends Service {
+  config: Config;
+  static inject: string[];
+  static Config: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    maxSteps: z.ZodDefault<z.ZodNumber>;
+    confirmTimeout: z.ZodDefault<z.ZodNumber>;
+    dailyTokens: z.ZodDefault<z.ZodNumber>;
+  }, z.core.$strip>;
+  private home;
+  private running;
+  private pluginSkills;
+  private settingsCache?;
+  constructor(ctx: Context, config: Config);
+  [Service.init](): Generator<() => void, void, unknown>;
+  /** Tools offered to the model: every action except the Agent's own and those turned off. */
+  tools(): Promise<ToolDefinition[]>;
+  settings(): Promise<AgentSettings>;
+  private updateSettings;
+  private policyOf;
+  /** Every action with its policy, for the tool policy table. */
+  policies(): Promise<{
+    name: string;
+    description: string;
+    plugin: string;
+    risk: import("@mushinjs/core").Risk;
+    client: boolean;
+    policy: ToolPolicy;
+    custom: boolean;
+  }[]>;
+  /** Sets the policy of some actions; `null` goes back to the default for the action's risk. */
+  setPolicy(changes: Record<string, ToolPolicy | null>): Promise<{
+    name: string;
+    description: string;
+    plugin: string;
+    risk: import("@mushinjs/core").Risk;
+    client: boolean;
+    policy: ToolPolicy;
+    custom: boolean;
+  }[]>;
+  profiles(): Promise<Record<string, SceneProfile>>;
+  setProfile(scene: string, profile: SceneProfile | null): Promise<SceneProfile>;
+  /** Tokens used today and the daily budget. */
+  usage(): Promise<{
+    budget: number;
+    day: string;
+    input: number;
+    output: number;
+  }>;
+  private addUsage;
+  private emit;
+  private allSessions;
+  private summary;
+  sessions(): Promise<{
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    scene: SessionScene | undefined;
+    tags: string[];
+    running: boolean;
+  }[]>;
+  /**
+   * Conversations matching every tag (`scene:flowEditor`, `skill:<id>`, `status:running`, …) and
+   * containing the query in the title or in what the user or the Agent wrote.
+   */
+  search(options?: {
+    query?: string;
+    tags?: string[];
+    limit?: number;
+  }): Promise<{
+    snippet?: string | undefined;
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    scene: SessionScene | undefined;
+    tags: string[];
+    running: boolean;
+  }[]>;
+  /** Adds a skill from a plugin; removed when the plugin unloads. */
+  defineSkill(definition: SkillDefinition): import("cordis").Disposable<Promise<void>>;
+  /** Built-in, plugin and user skills; user skills win on the same id. */
+  skills(): Promise<AgentSkill[]>;
+  skill(id: string): Promise<AgentSkill>;
+  /** Saves a user skill. With the id of a built-in or plugin skill it replaces that one until deleted. */
+  saveSkill(input: SkillDefinition & {
+    enabled?: boolean;
+  }): Promise<AgentSkill>;
+  createSkill(input: Omit<SkillDefinition, 'id'> & {
+    id?: string;
+  }): Promise<AgentSkill>;
+  updateSkill(id: string, patch: Partial<Omit<SkillDefinition, 'id'>>): Promise<AgentSkill>;
+  /** Deletes a user skill; a built-in or plugin skill it replaced comes back. */
+  deleteSkill(id: string): Promise<{
+    deleted: string;
+    restored: boolean;
+  }>;
+  setSkillEnabled(id: string, enabled: boolean): Promise<AgentSkill>;
+  /** Agent commands and the commands of every bot, for the `/` picker. */
+  commands(): {
+    builtin: {
+      name: string;
+      description: string;
+      'zh-CN': string;
+    }[];
+    bots: any;
+  };
+  session(id: string): Promise<AgentSession>;
+  createSession(): Promise<AgentSession>;
+  deleteSession(id: string): Promise<{
+    deleted: string;
+  }>;
+  private save;
+  private turnContext;
+  /** A bot's chat around one message, for quoting into an Agent message. */
+  private quoteChat;
+  /** Starts a turn and returns once it finishes. Progress streams as `agent/event` events. */
+  send(sessionId: string | undefined, text: string, options?: SendOptions): Promise<{
+    session: string;
+  }>;
+  private loop;
+  private runTool;
+  private waitForApproval;
+  confirm(sessionId: string, callId: string, approved: boolean): {
+    ok: boolean;
+  };
+  cancel(sessionId: string): {
+    ok: boolean;
+  };
+  status(): {
+    ready: boolean;
+    providers: number;
+    running: string[];
+  };
+  private defineActions;
+}
+export { Agent as default, AgentSettings, AgentSkill, BUILTIN_SKILLS, CustomRecommendation, SCENE_KEYS, SYSTEM_PROMPT, SceneInfo, SceneProfile, SkillDefinition, SkillSource, TokenUsage, ToolPolicy, TurnContext, contextNote, defaultPolicy, formatSkillMarkdown, parseSkillMarkdown, policyInput, profileInput, skillBlock, skillFields, skillInput, today };