xyne-plugin 1.0.2 → 1.1.0

package/package.json

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

package/src/hooks.ts

@@ -18,6 +18,115 @@ export interface ModelSpec {
 /** LLM message — opaque to plugins, passed through for transformation. */
 export type Message = Record<string, unknown>
 
+/** How a provider's API key was resolved. */
+export type CredentialSource = "config" | "env" | "auth"
+
+/** 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 }>
+}
+
+// ─── Message & Part types for hook signatures ────────────────────────────────
+
+/** Token usage breakdown. */
+export interface TokenInfo {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  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). */
+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
+}
+
+/** 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 }
+
+// ─── Plugin agent types ─────────────────────────────────────────────────────
+
+/**
+ * Simplified agent definition for plugins.
+ *
+ * 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
+ * - `permission` accepts a simple string map instead of a raw Permission.Ruleset
+ */
+export interface PluginAgentDef {
+  description?: string
+  mode?: "primary" | "subagent" | "all"
+  system?: string
+  /** Model override as "providerID/modelID" string or structured spec. */
+  model?: string | { providerID: string; modelID: string }
+  /** 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 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">>
+  maxSteps?: number
+  color?: string
+  hidden?: boolean
+  temperature?: number
+  topP?: number
+}
+
 // ─── Plugin function types ───────────────────────────────────────────────────
 
 export type PluginInput = {
@@ -26,10 +135,106 @@ export type PluginInput = {
   appName: string
   /** SDK client — available for plugins that need session/message/tool APIs. */
   client?: unknown
+  /** Base URL for the local server (if running). */
+  serverUrl?: URL
+  /** Bun shell for running commands. */
+  $?: unknown
 }
 
 export type Plugin = (input: PluginInput) => Promise<Hooks>
 
+// ─── Auth types ─────────────────────────────────────────────────────────────
+
+export type AuthPrompt =
+  | {
+      type: "text"
+      key: string
+      message: string
+      placeholder?: string
+      validate?: (value: string) => string | undefined
+      condition?: (inputs: Record<string, string>) => boolean
+    }
+  | {
+      type: "select"
+      key: string
+      message: string
+      options: Array<{ label: string; value: string; hint?: string }>
+      condition?: (inputs: Record<string, string>) => boolean
+    }
+
+export type AuthOAuthResult = { url: string; instructions: string } & (
+  | {
+      method: "auto"
+      callback(): Promise<
+        | ({ type: "success"; provider?: string } & (
+            | { refresh: string; access: string; expires: number; accountId?: string }
+            | { key: string }
+          ))
+        | { type: "failed" }
+      >
+    }
+  | {
+      method: "code"
+      callback(code: string): Promise<
+        | ({ type: "success"; provider?: string } & (
+            | { refresh: string; access: string; expires: number; accountId?: string }
+            | { key: string }
+          ))
+        | { type: "failed" }
+      >
+    }
+)
+
+export type AuthMethod =
+  | {
+      type: "oauth"
+      label: string
+      prompts?: AuthPrompt[]
+      authorize(inputs?: Record<string, string>): Promise<AuthOAuthResult>
+    }
+  | {
+      type: "api"
+      label: string
+      prompts?: AuthPrompt[]
+      authorize?(inputs?: Record<string, string>): Promise<
+        | { type: "success"; key: string; provider?: string }
+        | { type: "failed" }
+      >
+    }
+  | {
+      type: "custom"
+      label: string
+      prompts?: AuthPrompt[]
+      /** Plugin handles the entire auth flow. UI shows "Connecting..." while this runs. */
+      authorize(inputs?: Record<string, string>): Promise<
+        | { type: "success"; data: Record<string, unknown> }
+        | { type: "failed" }
+      >
+    }
+
+/**
+ * Options returned by an auth loader to configure the provider SDK.
+ */
+export interface AuthLoaderResult {
+  baseURL?: string
+  apiKey?: string
+  fetch?: typeof globalThis.fetch
+  /** Custom model selector — receives the SDK instance, model ID, and options. */
+  getModel?: (sdk: unknown, modelID: string, options: Record<string, unknown>) => Promise<unknown>
+  [key: string]: unknown
+}
+
+export type AuthHook = {
+  provider: string
+  /**
+   * 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.)
+   */
+  loader?: (auth: () => Promise<unknown>, provider: unknown) => Promise<AuthLoaderResult>
+  methods: AuthMethod[]
+}
+
 // ─── Hook definitions ────────────────────────────────────────────────────────
 
 export interface Hooks {
@@ -42,18 +247,34 @@ export interface Hooks {
   /** Register custom tools. Keyed by tool ID. */
   tool?: Record<string, ToolDefinition>
 
-  /** Auth provider stub — expand later with full OAuth / API key flows. */
-  auth?: { provider: string }
+  /** Register custom agents. Keyed by agent name. */
+  agent?: Record<string, PluginAgentDef>
+
+  /** Auth provider — OAuth, API key, or custom auth flows. */
+  auth?: AuthHook
+
+  /** Called when a new message is created (user or assistant). */
+  "chat.message"?: (
+    input: {
+      sessionID: string
+      messageID: string
+      role: string
+      agent?: string
+      model?: { providerID: string; modelID: string }
+      variant?: string
+    },
+    output: { message: MessageInfo; parts: PartInfo[] },
+  ) => Promise<void>
 
   /** Mutate LLM sampling parameters before a chat request. */
   "chat.params"?: (
-    input: { sessionID: string; agent: string; model: ModelSpec },
-    output: { temperature?: number; topP?: number; topK?: number },
+    input: { sessionID: string; agent: string; model: ModelSpec; provider?: ProviderInfo; message?: MessageInfo },
+    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 },
+    input: { sessionID: string; agent: string; model: ModelSpec; provider?: ProviderInfo; message?: MessageInfo },
     output: { headers: Record<string, string> },
   ) => Promise<void>
 
@@ -75,6 +296,12 @@ export interface Hooks {
     output: { status: "ask" | "deny" | "allow" },
   ) => Promise<void>
 
+  /** Called before a slash command executes. */
+  "command.execute.before"?: (
+    input: { command: string; sessionID: string; arguments: string },
+    output: { parts: PartInfo[] },
+  ) => Promise<void>
+
   /** Modify tool args before execution. */
   "tool.execute.before"?: (
     input: { tool: string; sessionID: string; callID: string },
@@ -104,4 +331,10 @@ export interface Hooks {
     input: { sessionID: string },
     output: { context: string[]; prompt?: string },
   ) => Promise<void>
+
+  /** Text completion hook — modify or provide text completions. */
+  "text.complete"?: (
+    input: { text: string; cursorOffset: number },
+    output: { completions: string[] },
+  ) => Promise<void>
 }

package/src/index.ts

@@ -22,11 +22,11 @@
  */
 
 // Plugin types
-export type { Plugin, PluginInput, Hooks } from "./hooks"
+export type { Plugin, PluginInput, Hooks, PluginAgentDef, AuthHook, AuthMethod, AuthPrompt, AuthOAuthResult, AuthLoaderResult, ModelSpec, ProviderInfo, CredentialSource, MessageInfo, PartInfo, ToolState, TokenInfo, MessageError } from "./hooks"
 
 // Tool authoring
 export { tool } from "./tool"
-export type { ToolDefinition, ToolContext } from "./tool"
+export type { ToolDefinition, ToolContext, ToolAuthConfig, ServiceCredentials, ToolAttachment, PluginToolResult } from "./tool"
 
 // Zod re-export for convenience
 export { z } from "zod"

package/src/tool.ts

@@ -1,4 +1,47 @@
 import { z } from "zod"
+import type { AuthMethod } from "./hooks"
+
+// ─── Service credentials ────────────────────────────────────────────────────
+
+/** Resolved service credentials injected into tool context. */
+export type ServiceCredentials =
+  | { type: "oauth"; access: string; refresh: string; expires: number }
+  | { type: "api"; key: string }
+  | { type: "custom"; data: Record<string, unknown> }
+
+// ─── Tool auth config ───────────────────────────────────────────────────────
+
+/**
+ * Declares that a tool requires authentication with an external service.
+ *
+ * When a tool with `auth` is executed:
+ * 1. The system checks stored credentials for `serviceID`
+ * 2. If found and not expired → credentials injected into `ctx.credentials`
+ * 3. If expired → `refresh` callback is tried first (silent refresh)
+ * 4. If missing or refresh fails → auth flow triggered via bus event, execution blocks
+ *    until user completes auth, then resumes with credentials
+ */
+export interface ToolAuthConfig {
+  /** Unique service identifier used as the storage key (e.g. "google-gmail", "jira"). */
+  serviceID: string
+  /** Human-readable label shown in auth prompts (e.g. "Google Gmail"). */
+  label: string
+  /** Auth methods — reuses the same AuthMethod type as provider auth (OAuth, API key, custom). */
+  methods: AuthMethod[]
+  /** Optional refresh callback — called when stored OAuth token is expired.
+   *  Receives the current credentials, returns refreshed credentials.
+   *  If this throws, falls through to full re-auth flow. */
+  refresh?: (entry: ServiceCredentials) => Promise<ServiceCredentials>
+  /** Optional custom credential storage. Defaults to auth.json (0o600 permissions).
+   *  Plugins can provide their own storage (e.g. system keychain, encrypted vault). */
+  storage?: {
+    get(): Promise<ServiceCredentials | undefined>
+    set(entry: ServiceCredentials): Promise<void>
+    remove(): Promise<void>
+  }
+}
+
+// ─── Tool context ───────────────────────────────────────────────────────────
 
 /**
  * Execution context passed to every custom tool's execute function.
@@ -20,6 +63,19 @@ export type ToolContext = {
   abort: AbortSignal
   metadata(input: { title?: string; metadata?: { [key: string]: unknown } }): void
   ask(input: AskInput): Promise<void>
+  /**
+   * Service credentials for this tool's declared `auth` service.
+   * Populated automatically before execute() when the tool has a `ToolAuthConfig`
+   * and the user has authenticated. Undefined if no auth is declared.
+   */
+  credentials?: ServiceCredentials
+  /**
+   * Clear cached credentials and re-trigger the auth flow.
+   * Call this when the external API returns 401/403 (token revoked).
+   * Returns fresh credentials after the user re-authenticates.
+   * Only available on tools that declare `auth`.
+   */
+  reauth?: () => Promise<ServiceCredentials>
 }
 
 type AskInput = {
@@ -29,6 +85,28 @@ type AskInput = {
   metadata: { [key: string]: unknown }
 }
 
+// ─── Tool definition ────────────────────────────────────────────────────────
+
+export interface ToolAttachment {
+  type: "file"
+  mime: string
+  /** Data URL (data:mime;base64,...) or file:// URL */
+  url: string
+}
+
+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>
+  auth?: ToolAuthConfig
+  execute(args: Record<string, unknown>, context: ToolContext): Promise<PluginToolResult>
+}
+
 /**
  * Define a custom tool. Use this in plugin packages or local tool files.
  *
@@ -50,11 +128,11 @@ type AskInput = {
 export function tool<Args extends z.ZodRawShape>(input: {
   description: string
   args: Args
-  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string>
-}) {
+  /** Optional auth requirement — tool execution will pause for auth if credentials are missing. */
+  auth?: ToolAuthConfig
+  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<PluginToolResult>
+}): ToolDefinition {
   return input
 }
 
 tool.schema = z
-
-export type ToolDefinition = ReturnType<typeof tool>