xyne-plugin 1.0.2

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "xyne-plugin",
+  "version": "1.0.2",
+  "description": "SDK for writing Xyne plugins — define custom tools, hooks, and extensions",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xyne",
+    "plugin",
+    "ai",
+    "agent",
+    "coding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xynehq/xyne.git",
+    "directory": "npm/xyne-plugin"
+  },
+  "dependencies": {
+    "zod": "^3.25.0"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,107 @@
+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
+}
+
+/** LLM message — opaque to plugins, passed through for transformation. */
+export type Message = Record<string, unknown>
+
+// ─── Plugin function types ───────────────────────────────────────────────────
+
+export type PluginInput = {
+  directory: string
+  worktree: string
+  appName: string
+  /** SDK client — available for plugins that need session/message/tool APIs. */
+  client?: unknown
+}
+
+export type Plugin = (input: PluginInput) => Promise<Hooks>
+
+// ─── Hook definitions ────────────────────────────────────────────────────────
+
+export interface Hooks {
+  /** Subscribe to bus events. */
+  event?: (input: { event: unknown }) => Promise<void>
+
+  /** Called once after all plugins are loaded — receive merged config. */
+  config?: (input: Record<string, unknown>) => Promise<void>
+
+  /** 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 }
+
+  /** Mutate LLM sampling parameters before a chat request. */
+  "chat.params"?: (
+    input: { sessionID: string; agent: string; model: ModelSpec },
+    output: { temperature?: number; topP?: number; topK?: number },
+  ) => Promise<void>
+
+  /** Inject extra HTTP headers into the provider request. */
+  "chat.headers"?: (
+    input: { sessionID: string; agent: string; model: ModelSpec },
+    output: { headers: Record<string, string> },
+  ) => Promise<void>
+
+  /** Transform the system prompt parts before they are joined. */
+  "chat.system.transform"?: (
+    input: { sessionID: string; model: ModelSpec },
+    output: { system: string[] },
+  ) => Promise<void>
+
+  /** Transform the message array before it is sent to the LLM. */
+  "chat.messages.transform"?: (
+    input: { sessionID: string },
+    output: { messages: Message[] },
+  ) => Promise<void>
+
+  /** Intercept permission decisions. */
+  "permission.ask"?: (
+    input: { permission: string; patterns: string[]; metadata: Record<string, unknown> },
+    output: { status: "ask" | "deny" | "allow" },
+  ) => Promise<void>
+
+  /** Modify tool args before execution. */
+  "tool.execute.before"?: (
+    input: { tool: string; sessionID: string; callID: string },
+    output: { args: unknown },
+  ) => Promise<void>
+
+  /** Modify tool output after execution. */
+  "tool.execute.after"?: (
+    input: { tool: string; sessionID: string; callID: string; args: unknown },
+    output: { title: string; output: string; metadata: unknown },
+  ) => Promise<void>
+
+  /** Modify a tool's description or parameters at registration time. */
+  "tool.definition"?: (
+    input: { toolID: string },
+    output: { description: string; parameters: unknown },
+  ) => Promise<void>
+
+  /** Inject environment variables into bash tool spawns. */
+  "shell.env"?: (
+    input: { cwd: string; sessionID?: string; callID?: string },
+    output: { env: Record<string, string> },
+  ) => Promise<void>
+
+  /** Customise context preservation during session compaction. */
+  "session.compacting"?: (
+    input: { sessionID: string },
+    output: { context: string[]; prompt?: string },
+  ) => Promise<void>
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * xyne-plugin — SDK for writing Xyne plugins.
+ *
+ * @example
+ * ```ts
+ * import { type Plugin, tool, z } from "xyne-plugin"
+ *
+ * const plugin: Plugin = async ({ directory }) => ({
+ *   tool: {
+ *     "my-tool": tool({
+ *       description: "Does something",
+ *       args: { query: z.string().describe("Search query") },
+ *       async execute(args, ctx) {
+ *         return `Result for ${args.query}`
+ *       },
+ *     }),
+ *   },
+ * })
+ *
+ * export default plugin
+ * ```
+ */
+
+// Plugin types
+export type { Plugin, PluginInput, Hooks } from "./hooks"
+
+// Tool authoring
+export { tool } from "./tool"
+export type { ToolDefinition, ToolContext } from "./tool"
+
+// Zod re-export for convenience
+export { z } from "zod"

package/src/tool.ts

@@ -0,0 +1,60 @@
+import { z } from "zod"
+
+/**
+ * Execution context passed to every custom tool's execute function.
+ */
+export type ToolContext = {
+  sessionID: string
+  messageID: string
+  agent: string
+  /**
+   * Current project directory for this session.
+   * Prefer this over process.cwd() when resolving relative paths.
+   */
+  directory: string
+  /**
+   * Project worktree root for this session.
+   * Useful for generating stable relative paths (e.g. path.relative(worktree, absPath)).
+   */
+  worktree: string
+  abort: AbortSignal
+  metadata(input: { title?: string; metadata?: { [key: string]: unknown } }): void
+  ask(input: AskInput): Promise<void>
+}
+
+type AskInput = {
+  permission: string
+  patterns: string[]
+  always: string[]
+  metadata: { [key: string]: unknown }
+}
+
+/**
+ * Define a custom tool. Use this in plugin packages or local tool files.
+ *
+ * @example
+ * ```ts
+ * import { tool, z } from "xyne-plugin"
+ *
+ * export default tool({
+ *   description: "Search the web",
+ *   args: {
+ *     query: z.string().describe("Search query"),
+ *   },
+ *   async execute(args, ctx) {
+ *     return `Results for ${args.query}`
+ *   },
+ * })
+ * ```
+ */
+export function tool<Args extends z.ZodRawShape>(input: {
+  description: string
+  args: Args
+  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string>
+}) {
+  return input
+}
+
+tool.schema = z
+
+export type ToolDefinition = ReturnType<typeof tool>