xyne-plugin 1.2.22 → 1.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xyne-plugin",
-  "version": "1.2.22",
+  "version": "1.2.26",
   "description": "SDK for writing Xyne plugins — define custom tools, hooks, and extensions",
   "type": "module",
   "exports": {

package/src/hooks.ts

@@ -1,16 +1,20 @@
+/**
+ * Plugin hook type definitions.
+ *
+ * A plugin is a function that receives context about the current workspace
+ * and returns a bag of hooks the host can call at various extension points.
+ *
+ * Pattern: `Plugin = (input) => Promise<Hooks>`
+ */
+
 import type { ToolDefinition } from "./tool"
 
 // ─── Simplified types for hook signatures ───────────────────────────────────
-// These are minimal versions of internal types — just enough for plugin authors
-// to work with hook parameters.
 
 /** Model descriptor passed to chat hooks. */
 export interface ModelSpec {
-  /** Model identifier, e.g. "claude-opus-4-6" */
   id: string
-  /** Provider identifier, e.g. "anthropic" */
   providerID: string
-  /** Human-readable name */
   name: string
   [key: string]: unknown
 }
@@ -31,8 +35,6 @@ export interface ProviderInfo {
   models: Record<string, { name: string; contextLength: number; maxOutputTokens: number; [key: string]: unknown }>
 }
 
-// ─── Message & Part types for hook signatures ────────────────────────────────
-
 /** Token usage breakdown. */
 export interface TokenInfo {
   input: number
@@ -42,58 +44,29 @@ export interface TokenInfo {
   reasoning: number
 }
 
-/** Error descriptor attached to failed messages. */
-export type MessageError =
-  | { name: "AuthError"; providerID: string; message: string }
-  | { name: "APIError"; message: string; statusCode?: number; isRetryable: boolean }
-  | { name: "ContextOverflowError"; message: string }
-  | { name: "AbortedError"; message: string }
-  | { name: "OutputLengthError" }
-  | { name: "StructuredOutputError"; message: string; retries: number }
-  | { name: "Unknown"; message: string }
-
-/** A message in the session (user or assistant turn). */
+/** Message info passed to hooks. */
 export interface MessageInfo {
   id: string
   sessionID: string
   role: "user" | "assistant"
   created: number
   completed?: number
-  parentID?: string
   agentID?: string
   modelID?: string
   providerID?: string
-  path?: { cwd: string; root: string }
-  finish?: string
-  error?: MessageError
-  cost?: number
   tokens?: TokenInfo
-  requestedModel?: { providerID: string; modelID: string }
-  format?: { type: string; [key: string]: unknown }
-  structured?: unknown
-  summary?: string
+  cost?: number
+  [key: string]: unknown
 }
 
-/** Tool call state. */
-export type ToolState =
-  | { status: "pending" }
-  | { status: "running"; input: unknown; startTime: number; title?: string; metadata?: unknown }
-  | { status: "completed"; input: unknown; output: string; title: string; metadata: unknown; startTime: number; endTime: number; attachments?: Array<{ type: string; url: string; mime: string }>; compacted?: number }
-  | { status: "error"; input: unknown; error: string; startTime: number; endTime: number }
-
-/** Discriminated union of all part types. */
-export type PartInfo =
-  | { type: "text"; id: string; messageID: string; sessionID: string; text: string; startTime: number; endTime?: number; metadata?: Record<string, unknown>; synthetic?: boolean; ignored?: boolean }
-  | { type: "reasoning"; id: string; messageID: string; sessionID: string; text: string; startTime: number; endTime?: number; metadata?: Record<string, unknown> }
-  | { type: "tool"; id: string; messageID: string; sessionID: string; callID: string; tool: string; state: ToolState }
-  | { type: "step-start"; id: string; messageID: string; sessionID: string }
-  | { type: "step-finish"; id: string; messageID: string; sessionID: string; reason: string; tokens?: TokenInfo; cost?: number }
-  | { type: "retry"; id: string; messageID: string; sessionID: string; attempt: number; error: MessageError; time: { created: number } }
-  | { type: "compaction"; id: string; messageID: string; sessionID: string; auto: boolean; overflow?: boolean }
-  | { type: "subtask"; id: string; messageID: string; sessionID: string; prompt: string; description: string; agent: string; model?: { providerID: string; modelID: string }; command?: string }
-  | { type: "patch"; id: string; messageID: string; sessionID: string; hash: string; files: string[] }
-  | { type: "media"; id: string; messageID: string; sessionID: string; mime: string; filename?: string; url: string }
-  | { type: "agent"; id: string; messageID: string; sessionID: string; name: string }
+/** Part info passed to hooks. */
+export interface PartInfo {
+  id: string
+  messageID: string
+  sessionID: string
+  type: string
+  [key: string]: unknown
+}
 
 // ─── Plugin agent types ─────────────────────────────────────────────────────
 
@@ -102,7 +75,9 @@ export type PartInfo =
  *
  * Plugin agents follow the same Agent.Info shape but use a reduced surface:
  * - `name` is derived from the record key
- * - `tools` is a record of ToolDefinitions that are converted to Tool.Info[] at registration time
+ * - `native` is always false
+ * - `tools` is a record of ToolDefinitions (same format as plugin tools)
+ *   that are converted to Tool.Info[] at registration time
  * - `permission` accepts a simple string map instead of a raw Permission.Ruleset
  */
 export interface PluginAgentDef {
@@ -114,12 +89,14 @@ export interface PluginAgentDef {
   /** Tools scoped to this agent. These are added on top of session tools. */
   tools?: Record<string, ToolDefinition>
   /**
-   * If true, this agent ONLY has access to its own `tools` (built-in session tools are excluded).
+   * If true, this agent ONLY has access to its own `tools` (plus built-in session tools are excluded).
    * If false (default), the agent's tools are merged with the session's tool set.
    */
   isolatedTools?: boolean
   /** Permission overrides. Keys are tool IDs or "*", values are "allow" | "deny" | "ask". */
   permission?: Record<string, "allow" | "deny" | "ask" | Record<string, "allow" | "deny" | "ask">>
+  /** Subagent names this agent can spawn via the Task tool. If unset, all subagents are available. */
+  agents?: string[]
   maxSteps?: number
   color?: string
   hidden?: boolean
@@ -127,6 +104,18 @@ export interface PluginAgentDef {
   topP?: number
 }
 
+// ─── Provider context for chat hooks ────────────────────────────────────────
+
+/** Provider metadata exposed to plugin hooks. */
+export interface ProviderInfo {
+  id: string
+  name: string
+  source: CredentialSource
+  env: string[]
+  options: Record<string, unknown>
+  models: Record<string, { name: string; contextLength: number; maxOutputTokens: number; [key: string]: unknown }>
+}
+
 // ─── Plugin function types ───────────────────────────────────────────────────
 
 export type PluginInput = {
@@ -134,11 +123,11 @@ export type PluginInput = {
   worktree: string
   appName: string
   /** SDK client — available for plugins that need session/message/tool APIs. */
-  client?: unknown
+  client?: unknown | undefined
   /** Base URL for the local server (if running). */
-  serverUrl?: URL
+  serverUrl?: URL | undefined
   /** Bun shell for running commands. */
-  $?: unknown
+  $?: unknown | undefined
 }
 
 export type Plugin = (input: PluginInput) => Promise<Hooks>
@@ -206,7 +195,7 @@ export type AuthMethod =
       label: string
       /** Message shown in the TUI while authorize() runs (default: "Connecting..."). */
       pendingMessage?: string
-      /** Hint shown below the pending message. */
+      /** Hint shown below the pending message (e.g. "Waiting for approval... · esc cancel"). */
       pendingHint?: string
       prompts?: AuthPrompt[]
       /** Plugin handles the entire auth flow. UI shows pendingMessage while this runs. */
@@ -218,6 +207,10 @@ export type AuthMethod =
 
 /**
  * Options returned by an auth loader to configure the provider SDK.
+ *
+ * Standard SDK options (baseURL, apiKey, fetch) are merged into the SDK factory call.
+ * The optional `getModel` callback lets the loader control model selection
+ * (e.g. routing gpt-5 to a responses API vs chat API).
  */
 export interface AuthLoaderResult {
   baseURL?: string
@@ -234,6 +227,7 @@ export type AuthHook = {
    * Called after auth succeeds to configure the provider SDK.
    * Receives a getter for the auth entry and the provider info.
    * Returns SDK options (baseURL, apiKey, fetch, getModel, etc.)
+   * that are merged into the provider's SDK configuration.
    */
   loader?: (auth: () => Promise<unknown>, provider: unknown) => Promise<AuthLoaderResult>
   methods: AuthMethod[]
@@ -279,13 +273,13 @@ export interface Hooks {
 
   /** Mutate LLM sampling parameters before a chat request. */
   "chat.params"?: (
-    input: { sessionID: string; agent: string; model: ModelSpec; provider?: ProviderInfo; message?: MessageInfo },
+    input: { sessionID: string; agent: string; model: ModelSpec; provider?: ProviderInfo | undefined; message?: MessageInfo | undefined },
     output: { temperature?: number; topP?: number; topK?: number; options?: Record<string, unknown> },
   ) => Promise<void>
 
   /** Inject extra HTTP headers into the provider request. */
   "chat.headers"?: (
-    input: { sessionID: string; agent: string; model: ModelSpec; provider?: ProviderInfo; message?: MessageInfo },
+    input: { sessionID: string; agent: string; model: ModelSpec; provider?: ProviderInfo | undefined; message?: MessageInfo | undefined },
     output: { headers: Record<string, string> },
   ) => Promise<void>
 
@@ -313,15 +307,20 @@ export interface Hooks {
     output: { parts: PartInfo[] },
   ) => Promise<void>
 
-  /** Modify tool args before execution. */
+  /**
+   * Modify tool args before execution, or block the tool call entirely.
+   *
+   * To block: set `output.blocked = true` and optionally `output.reason = "why"`.
+   * The reason is returned to the LLM as the tool output so it can adapt.
+   */
   "tool.execute.before"?: (
-    input: { tool: string; sessionID: string; callID: string },
-    output: { args: unknown },
+    input: { tool: string; sessionID: string; callID: string; agent: string; isSubagent: boolean },
+    output: { args: unknown; blocked?: boolean; reason?: string },
   ) => Promise<void>
 
   /** Modify tool output after execution. */
   "tool.execute.after"?: (
-    input: { tool: string; sessionID: string; callID: string; args: unknown },
+    input: { tool: string; sessionID: string; callID: string; agent: string; isSubagent: boolean; args: unknown },
     output: { title: string; output: string; metadata: unknown },
   ) => Promise<void>
 
@@ -340,7 +339,7 @@ export interface Hooks {
   /** Customise context preservation during session compaction. */
   "session.compacting"?: (
     input: { sessionID: string },
-    output: { context: string[]; prompt?: string },
+    output: { context: string[]; prompt?: string | undefined },
   ) => Promise<void>
 
   /** Text completion hook — modify or provide text completions. */

package/src/index.ts

@@ -1,9 +1,9 @@
 /**
- * xyne-plugin — SDK for writing Xyne plugins.
+ * @xyne/plugin — SDK for writing Xyne plugins.
  *
  * @example
  * ```ts
- * import { type Plugin, tool, z } from "xyne-plugin"
+ * import { type Plugin, tool, z } from "@xyne/plugin"
  *
  * const plugin: Plugin = async ({ directory }) => ({
  *   tool: {
@@ -22,11 +22,11 @@
  */
 
 // Plugin types
-export type { Plugin, PluginInput, Hooks, PluginAgentDef, AuthHook, AuthMethod, AuthPrompt, AuthOAuthResult, AuthLoaderResult, ModelSpec, ProviderInfo, CredentialSource, MessageInfo, PartInfo, ToolState, TokenInfo, MessageError } from "./hooks"
+export type { PluginFn as Plugin, PluginInput, Hooks, PluginAgentDef, AuthMethod, AuthPrompt, AuthOAuthResult } from "@tui/agent-core"
 
 // Tool authoring
-export { tool } from "./tool"
-export type { ToolDefinition, ToolContext, ToolAuthConfig, ServiceCredentials, ToolAttachment, PluginToolResult } from "./tool"
+export { tool } from "@tui/agent-core"
+export type { ToolDefinition, ToolContext, ToolAuthConfig, ServiceCredentials, ToolAttachment, PluginToolResult } from "@tui/agent-core"
 
 // Zod re-export for convenience
 export { z } from "zod"

package/src/tool.ts

@@ -63,6 +63,13 @@ export type ToolContext = {
   abort: AbortSignal
   metadata(input: { title?: string; metadata?: { [key: string]: unknown } }): void
   ask(input: AskInput): Promise<void>
+  /**
+   * Ask the user a free-text question and wait for their reply.
+   * Pauses the agent loop until the user submits an answer.
+   * Returns a string[][] — one string[] per question containing the selected/typed answers.
+   * Pass options: [] to render a plain free-text input with no predefined choices.
+   */
+  askQuestion(input: AskQuestionInput): Promise<string[][]>
   /**
    * Service credentials for this tool's declared `auth` service.
    * Populated automatically before execute() when the tool has a `ToolAuthConfig`
@@ -85,8 +92,46 @@ type AskInput = {
   metadata: { [key: string]: unknown }
 }
 
+type QuestionOption = {
+  label: string
+  description: string
+}
+
+type AskQuestionInput = {
+  questions: Array<{
+    question: string
+    /** Very short label shown in the tab bar (max 30 chars). Defaults to the first 30 chars of question. */
+    header?: string
+    /** Predefined choices. Pass [] or omit for a plain free-text input. */
+    options?: QuestionOption[]
+    multiple?: boolean
+  }>
+}
+
 // ─── Tool definition ────────────────────────────────────────────────────────
 
+/**
+ * Define a custom tool. Use this in .agent/tool/*.ts files or in plugin packages.
+ *
+ * @example
+ * ```ts
+ * import { tool } from "@tui/agent-core/plugin"
+ *
+ * export default tool({
+ *   description: "Does something useful",
+ *   args: {
+ *     query: tool.schema.string().describe("Search query"),
+ *   },
+ *   async execute(args, ctx) {
+ *     return "result"
+ *   },
+ * })
+ * ```
+ */
+/**
+ * The wide storage type used in Hooks.tool and internal registries.
+ * Plugin authors don't construct this directly — use the `tool()` factory.
+ */
 export interface ToolAttachment {
   type: "file"
   mime: string
@@ -96,10 +141,6 @@ export interface ToolAttachment {
 
 export type PluginToolResult = string | { text: string; attachments: ToolAttachment[] }
 
-/**
- * The wide storage type used in Hooks.tool and internal registries.
- * Plugin authors don't construct this directly — use the `tool()` factory.
- */
 export interface ToolDefinition {
   description: string
   args: Record<string, z.ZodType>
@@ -108,19 +149,17 @@ export interface ToolDefinition {
 }
 
 /**
- * Define a custom tool. Use this in plugin packages or local tool files.
+ * Define a custom tool. Args are inferred from the zod schema so
+ * `execute` gets strongly-typed parameters.
  *
  * @example
  * ```ts
- * import { tool, z } from "xyne-plugin"
- *
  * export default tool({
- *   description: "Search the web",
- *   args: {
- *     query: z.string().describe("Search query"),
- *   },
+ *   description: "Does something useful",
+ *   args: { query: tool.schema.string().describe("Search query") },
  *   async execute(args, ctx) {
- *     return `Results for ${args.query}`
+ *     args.query // ← string
+ *     return "result"
  *   },
  * })
  * ```