kanban-lite 1.2.3 → 1.2.4

package/dist/standalone.js

@@ -49920,6 +49920,10 @@ function loadDotEnv(dir2) {
   }
 }
 function resolveConfigEnvVars(node, configFileName, nodePath = "") {
+  const isFormDefaultDataPath = /^\.forms\.(?:[^.]+|"[^"]+")\.data(?:$|[.\[])/.test(nodePath);
+  if (isFormDefaultDataPath) {
+    return node;
+  }
   if (typeof node === "string") {
     return node.replace(/\$\{([^}]+)\}/g, (_match, varName) => {
       const envValue = process.env[varName];
@@ -61678,6 +61682,25 @@ var KanbanSDK = class _KanbanSDK {
   get workspaceRoot() {
     return path17.dirname(this.kanbanDir);
   }
+  /**
+   * Returns a cloned read-only snapshot of the current workspace config.
+   *
+   * The returned snapshot is created from a fresh config read and deep-cloned
+   * before being returned, so callers receive an isolated view of the current
+   * `.kanban.json` state rather than a live mutable runtime object. Mutating the
+   * returned snapshot does not update persisted config or affect this SDK instance.
+   *
+   * @returns A cloned read-only snapshot of the current {@link KanbanConfig}.
+   *
+   * @example
+   * ```ts
+   * const config = sdk.getConfigSnapshot()
+   * console.log(config.defaultBoard)
+   * ```
+   */
+  getConfigSnapshot() {
+    return structuredClone(readConfig(this.workspaceRoot));
+  }
   // --- Board resolution helpers ---
   /** @internal */
   _resolveBoardId(boardId) {
@@ -65218,9 +65241,14 @@ async function handleMessage(ctx, ws, message, authContext) {
 }
 
 // src/standalone/internal/websocket.ts
-function attachWebSocketHandlers(ctx) {
-  ctx.wss.on("connection", (ws, req) => {
-    const authContext = extractAuthContext(req);
+function attachWebSocketHandlers(ctx, resolveAuthContext) {
+  ctx.wss.on("connection", async (ws, req) => {
+    let authContext;
+    try {
+      authContext = resolveAuthContext ? await resolveAuthContext(req) : extractAuthContext(req);
+    } catch {
+      authContext = extractAuthContext(req);
+    }
     setClientEditingCard(ctx, ws, null);
     ws.on("message", (data) => {
       let message;
@@ -65387,6 +65415,7 @@ function isPageRequest(method, pathname) {
 function collectStandaloneHttpHandlers(requestType, ctx) {
   const plugins = ctx.sdk.capabilities?.standaloneHttpPlugins ?? [];
   const registrationOptions = {
+    sdk: ctx.sdk,
     workspaceRoot: ctx.workspaceRoot,
     kanbanDir: ctx.absoluteKanbanDir,
     capabilities: ctx.sdk.capabilities?.providers ?? {
@@ -65514,7 +65543,62 @@ function startServer(kanbanDir, port2, webviewDir, resolvedConfigPath) {
     }
     reply.hijack();
   });
-  attachWebSocketHandlers(ctx);
+  const resolveWsAuthContext = async (req) => {
+    const silentRes = /* @__PURE__ */ (() => {
+      const r = {
+        writableEnded: false,
+        writeHead() {
+          return r;
+        },
+        setHeader() {
+          return r;
+        },
+        removeHeader() {
+        },
+        getHeader() {
+          return void 0;
+        },
+        getHeaders() {
+          return {};
+        },
+        end(..._args) {
+          r.writableEnded = true;
+          return r;
+        },
+        write() {
+          return false;
+        }
+      };
+      return r;
+    })();
+    const reqWithBody = req;
+    const wsUrl = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+    const requestContext = {
+      ctx,
+      sdk: ctx.sdk,
+      workspaceRoot: ctx.workspaceRoot,
+      kanbanDir: ctx.absoluteKanbanDir,
+      req: reqWithBody,
+      res: silentRes,
+      url: wsUrl,
+      pathname: wsUrl.pathname,
+      method: "GET",
+      resolvedWebviewDir,
+      indexHtml: resolvedIndexHtml,
+      route: createRouteMatcher("GET", wsUrl.pathname, matchRoute),
+      isApiRequest: false,
+      isPageRequest: false,
+      getAuthContext: () => getRequestAuthContext(req),
+      setAuthContext: (auth) => setRequestAuthContext(req, auth),
+      mergeAuthContext: (auth) => mergeRequestAuthContext(req, auth)
+    };
+    for (const handler of middlewareHandlers) {
+      if (await handler(requestContext))
+        break;
+    }
+    return extractAuthContext(req);
+  };
+  attachWebSocketHandlers(ctx, resolveWsAuthContext);
   setupStandaloneLifecycle(ctx, fastify.server);
   const effectiveConfigPath = resolvedConfigPath ?? configPath(path20.dirname(ctx.absoluteKanbanDir));
   fastify.listen({ port: port2, host: "0.0.0.0" }, (err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanban-lite",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Kanban board manager - VSCode extension, CLI, MCP server, and standalone web app",
   "license": "MIT",
   "repository": {

package/src/cli/index.test.ts

@@ -53,6 +53,85 @@ function createCliAuthWorkspace(): { workspaceDir: string; configPath: string; c
   }
 }
 
+function createCliWorkspace(config: Record<string, unknown>): { workspaceDir: string; configPath: string; cleanup: () => void } {
+  const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kanban-cli-plugin-'))
+  fs.mkdirSync(path.join(workspaceDir, '.kanban'), { recursive: true })
+  const configPath = path.join(workspaceDir, '.kanban.json')
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify({
+      version: 2,
+      defaultBoard: 'default',
+      kanbanDirectory: '.kanban',
+      boards: {
+        default: {
+          name: 'Default',
+          columns: [{ id: 'backlog', name: 'Backlog' }],
+          nextCardId: 1,
+          defaultStatus: 'backlog',
+          defaultPriority: 'medium',
+        },
+      },
+      ...config,
+    }, null, 2) + '\n',
+    'utf-8',
+  )
+  return {
+    workspaceDir,
+    configPath,
+    cleanup: () => fs.rmSync(workspaceDir, { recursive: true, force: true }),
+  }
+}
+
+function installTempCliPlugin(packageName: string, entrySource: string): () => void {
+  const packageDir = path.join(WORKSPACE_ROOT, 'node_modules', packageName)
+  fs.mkdirSync(packageDir, { recursive: true })
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({ name: packageName, main: 'index.js' }, null, 2),
+    'utf-8',
+  )
+  fs.writeFileSync(path.join(packageDir, 'index.js'), entrySource, 'utf-8')
+  return () => fs.rmSync(packageDir, { recursive: true, force: true })
+}
+
+function createCliSdkProbePackageSource(packageName: string, command: string): string {
+  return [
+    "const fs = require('node:fs')",
+    `const packageName = ${JSON.stringify(packageName)}`,
+    `const command = ${JSON.stringify(command)}`,
+    'module.exports.authIdentityPlugin = {',
+    '  manifest: { id: packageName, provides: [\'auth.identity\'] },',
+    '  async resolveIdentity() { return null },',
+    '}',
+    'module.exports.cliPlugin = {',
+    '  manifest: { id: packageName },',
+    '  command,',
+    '  async run(subArgs, flags, context) {',
+    '    const runWithCliAuthResult = typeof context.runWithCliAuth === \"function\"',
+    '      ? await context.runWithCliAuth(() => Promise.resolve(\"ok\"))',
+    '      : null',
+    '    const payload = {',
+    '      subArgs,',
+    '      hasSdk: !!context.sdk,',
+    '      hasGetConfigSnapshot: typeof context.sdk?.getConfigSnapshot === \"function\",',
+    '      hasGetBoard: typeof context.sdk?.getBoard === "function",',
+    '      hasGetExtension: typeof context.sdk?.getExtension === \"function\",',
+    '      hasWorkspaceRootGetter: typeof context.sdk?.workspaceRoot === \"string\",',
+    '      snapshotDefaultBoard: context.sdk?.getConfigSnapshot?.().defaultBoard ?? null,',
+    '      defaultBoardName: context.sdk?.getBoard?.("default")?.name ?? null,',
+    '      runWithCliAuthResult,',
+    '      workspaceRoot: context.workspaceRoot,',
+    '      flagCount: Object.keys(flags || {}).length,',
+    '    }',
+    '    if (process.env.KANBAN_SDK_PROBE_OUTPUT) {',
+    '      fs.writeFileSync(process.env.KANBAN_SDK_PROBE_OUTPUT, JSON.stringify(payload, null, 2))',
+    '    }',
+    '  },',
+    '}',
+  ].join('\n')
+}
+
 async function createCliCardStateWorkspace(): Promise<{ workspaceDir: string; configPath: string; cardId: string; cleanup: () => void }> {
   const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kanban-cli-card-state-'))
   fs.mkdirSync(path.join(workspaceDir, '.kanban'), { recursive: true })
@@ -733,3 +812,81 @@ describe('Webhook CLI routing — plugin-owned dispatch', () => {
   })
 })
 
+describe('CLI plugin context SDK injection regressions', () => {
+  it('passes the full public SDK to standard CLI plugin commands', async () => {
+    const packageName = `kanban-cli-sdk-probe-${Date.now()}-standard`
+    const cleanupPlugin = installTempCliPlugin(
+      packageName,
+      createCliSdkProbePackageSource(packageName, 'sdk-probe'),
+    )
+    const { workspaceDir, configPath, cleanup } = createCliWorkspace({
+      auth: {
+        'auth.identity': { provider: packageName },
+      },
+    })
+    const markerPath = path.join(workspaceDir, 'sdk-probe-standard.json')
+
+    try {
+      const result = await runCliCommand(['sdk-probe', '--config', configPath], {
+        KANBAN_SDK_PROBE_OUTPUT: markerPath,
+      })
+
+      expect(result.exitCode).toBe(0)
+      const payload = JSON.parse(fs.readFileSync(markerPath, 'utf-8')) as Record<string, unknown>
+      expect(payload).toMatchObject({
+        subArgs: [],
+        hasSdk: true,
+        hasGetConfigSnapshot: true,
+        hasGetBoard: true,
+        hasGetExtension: true,
+        hasWorkspaceRootGetter: true,
+        snapshotDefaultBoard: 'default',
+        defaultBoardName: 'Default',
+        runWithCliAuthResult: 'ok',
+        workspaceRoot: workspaceDir,
+      })
+    } finally {
+      cleanup()
+      cleanupPlugin()
+    }
+  })
+
+  it('passes the full public SDK through the auth special-case CLI path', async () => {
+    const packageName = `kanban-cli-sdk-probe-${Date.now()}-auth`
+    const cleanupPlugin = installTempCliPlugin(
+      packageName,
+      createCliSdkProbePackageSource(packageName, 'auth'),
+    )
+    const { workspaceDir, configPath, cleanup } = createCliWorkspace({
+      auth: {
+        'auth.identity': { provider: packageName },
+      },
+    })
+    const markerPath = path.join(workspaceDir, 'sdk-probe-auth.json')
+
+    try {
+      const result = await runCliCommand(['auth', 'inspect', '--config', configPath], {
+        KANBAN_SDK_PROBE_OUTPUT: markerPath,
+      })
+
+      expect(result.exitCode).toBe(0)
+      const payload = JSON.parse(fs.readFileSync(markerPath, 'utf-8')) as Record<string, unknown>
+      expect(payload).toMatchObject({
+        subArgs: ['inspect'],
+        hasSdk: true,
+        hasGetConfigSnapshot: true,
+        hasGetBoard: true,
+        hasGetExtension: true,
+        hasWorkspaceRootGetter: true,
+        snapshotDefaultBoard: 'default',
+        defaultBoardName: 'Default',
+        runWithCliAuthResult: 'ok',
+        workspaceRoot: workspaceDir,
+      })
+    } finally {
+      cleanup()
+      cleanupPlugin()
+    }
+  })
+})
+

package/src/cli/index.ts

@@ -1869,7 +1869,7 @@ async function cmdAuth(sdk: KanbanSDK, positional: string[], flags: Flags, cliPl
   if (sub !== 'status') {
     const authPlugin = findCliPlugin(cliPlugins, 'auth')
     if (authPlugin) {
-      await authPlugin.run(positional, flags, { workspaceRoot })
+      await runCliPlugin(authPlugin, positional, flags, workspaceRoot, sdk)
       return
     }
     console.error(red(`Unknown auth sub-command: ${sub}`))

package/src/mcp-server/index.test.ts

@@ -581,6 +581,82 @@ describe('plugin-owned MCP webhook registration', () => {
     }
   })
 
+  it('keeps widened MCP plugin contexts compatible with full public SDK reads', async () => {
+    const tools: Array<{
+      name: string
+      description: string
+      schema: Record<string, unknown>
+      handler: (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>
+    }> = []
+
+    const server = {
+      tool(
+        name: string,
+        description: string,
+        schema: Record<string, unknown>,
+        handler: (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>,
+      ) {
+        tools.push({ name, description, schema, handler })
+      },
+    }
+
+    const probePlugin = {
+      manifest: { id: 'sdk-seam-probe', provides: ['mcp.tools'] as const },
+      registerTools: (ctx: ReturnType<typeof createMcpPluginContext>) => [{
+        name: 'sdk_snapshot_probe',
+        description: 'Regression probe for widened MCP SDK context.',
+        inputSchema: () => ({}),
+        handler: async () => ({
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              hasGetConfigSnapshot: typeof ctx.sdk.getConfigSnapshot === 'function',
+              hasGetBoard: typeof ctx.sdk.getBoard === 'function',
+              hasGetExtension: typeof ctx.sdk.getExtension === 'function',
+              defaultBoard: ctx.sdk.getConfigSnapshot().defaultBoard,
+              defaultBoardName: ctx.sdk.getBoard('default').name,
+              workspaceRoot: ctx.sdk.workspaceRoot,
+            }),
+          }],
+        }),
+      }],
+    }
+
+    const resolveSpy = vi.spyOn(pluginRegistry, 'resolveMcpPlugins').mockReturnValue([
+      mcpPlugin as never,
+      probePlugin as never,
+    ])
+
+    try {
+      const registered = registerPluginMcpTools(
+        server,
+        {},
+        createMcpPluginContext({
+          sdk,
+          workspaceRoot: workspaceDir,
+          kanbanDir,
+          runWithAuth: (fn) => sdk.runWithAuth({ transport: 'mcp' }, fn),
+        }),
+      )
+
+      expect(registered).toContain('sdk_snapshot_probe')
+      const probeTool = tools.find((tool) => tool.name === 'sdk_snapshot_probe')
+      expect(probeTool).toBeDefined()
+
+      const result = await probeTool!.handler({})
+      expect(JSON.parse(result.content[0].text)).toEqual({
+        hasGetConfigSnapshot: true,
+        hasGetBoard: true,
+        hasGetExtension: true,
+        defaultBoard: 'default',
+        defaultBoardName: 'Default',
+        workspaceRoot: workspaceDir,
+      })
+    } finally {
+      resolveSpy.mockRestore()
+    }
+  })
+
   it('rejects duplicate plugin-owned MCP tool registration for webhook tools', () => {
     const duplicatePlugin = {
       manifest: { id: 'duplicate-webhooks-test', provides: ['mcp.tools'] as const },

package/src/sdk/KanbanSDK.d.ts

@@ -1,6 +1,6 @@
 import type { Comment, Card, KanbanColumn, BoardInfo, LabelDefinition, CardSortOption, LogEntry } from '../shared/types';
 import type { CardDisplaySettings, Priority } from '../shared/types';
-import type { BoardConfig, ResolvedCapabilities, Webhook } from '../shared/config';
+import type { BoardConfig, KanbanConfig, ResolvedCapabilities, Webhook } from '../shared/config';
 import type { CreateCardInput, SDKEvent, SDKEventType, SDKOptions, SubmitFormInput, SubmitFormResult, AuthContext, AuthDecision, SDKBeforeEventType, SDKAfterEventType, CardStateStatus, CardUnreadSummary } from './types';
 import type { EventBusAnyListener, EventBusWaitOptions } from './eventBus';
 import { EventBus } from './eventBus';
@@ -67,6 +67,9 @@ export interface WebhookStatus {
 }
 /** Active card-state provider metadata for diagnostics and host surfaces. */
 export type CardStateRuntimeStatus = CardStateStatus;
+type ReadonlySnapshot<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer U)[] ? readonly ReadonlySnapshot<U>[] : T extends object ? {
+    readonly [K in keyof T]: ReadonlySnapshot<T[K]>;
+} : T;
 /**
  * Optional search and sort inputs for {@link KanbanSDK.listCards}.
  *
@@ -524,6 +527,23 @@ export declare class KanbanSDK {
      * ```
      */
     get workspaceRoot(): string;
+    /**
+     * Returns a cloned read-only snapshot of the current workspace config.
+     *
+     * The returned snapshot is created from a fresh config read and deep-cloned
+     * before being returned, so callers receive an isolated view of the current
+     * `.kanban.json` state rather than a live mutable runtime object. Mutating the
+     * returned snapshot does not update persisted config or affect this SDK instance.
+     *
+     * @returns A cloned read-only snapshot of the current {@link KanbanConfig}.
+     *
+     * @example
+     * ```ts
+     * const config = sdk.getConfigSnapshot()
+     * console.log(config.defaultBoard)
+     * ```
+     */
+    getConfigSnapshot(): ReadonlySnapshot<KanbanConfig>;
     /** @internal */
     _resolveBoardId(boardId?: string): string;
     /** @internal */

package/src/sdk/KanbanSDK.ts

@@ -4,7 +4,7 @@ import type { Comment, Card, KanbanColumn, BoardInfo, LabelDefinition, CardSortO
 import type { CardDisplaySettings, Priority } from '../shared/types'
 import { DELETED_STATUS_ID } from '../shared/types'
 import { readConfig, normalizeStorageCapabilities, normalizeAuthCapabilities, normalizeWebhookCapabilities, normalizeCardStateCapabilities } from '../shared/config'
-import type { BoardConfig, ProviderRef, ResolvedCapabilities, ResolvedWebhookCapabilities, ResolvedCardStateCapabilities, Webhook } from '../shared/config'
+import type { BoardConfig, KanbanConfig, ProviderRef, ResolvedCapabilities, ResolvedWebhookCapabilities, ResolvedCardStateCapabilities, Webhook } from '../shared/config'
 import type { ResolvedAuthCapabilities } from '../shared/config'
 import type { CreateCardInput, SDKEvent, SDKEventHandler, SDKEventType, SDKOptions, SubmitFormInput, SubmitFormResult, AuthContext, AuthDecision, SDKEventListenerPlugin, BeforeEventPayload, AfterEventPayload, SDKBeforeEventType, SDKAfterEventType, CardStateStatus, CardOpenStateValue, CardUnreadSummary } from './types'
 import type { EventBusAnyListener, EventBusWaitOptions } from './eventBus'
@@ -113,6 +113,15 @@ type MethodInput<TMethod> =
     ? TFirst
     : Record<string, unknown>
 
+type ReadonlySnapshot<T> =
+  T extends (...args: never[]) => unknown
+    ? T
+    : T extends readonly (infer U)[]
+      ? readonly ReadonlySnapshot<U>[]
+      : T extends object
+        ? { readonly [K in keyof T]: ReadonlySnapshot<T[K]> }
+        : T
+
 /**
  * Active webhook provider metadata for diagnostics and host surfaces.
  *
@@ -1158,6 +1167,26 @@ export class KanbanSDK {
     return path.dirname(this.kanbanDir)
   }
 
+  /**
+   * Returns a cloned read-only snapshot of the current workspace config.
+   *
+   * The returned snapshot is created from a fresh config read and deep-cloned
+   * before being returned, so callers receive an isolated view of the current
+   * `.kanban.json` state rather than a live mutable runtime object. Mutating the
+   * returned snapshot does not update persisted config or affect this SDK instance.
+   *
+   * @returns A cloned read-only snapshot of the current {@link KanbanConfig}.
+   *
+   * @example
+   * ```ts
+   * const config = sdk.getConfigSnapshot()
+   * console.log(config.defaultBoard)
+   * ```
+   */
+  getConfigSnapshot(): ReadonlySnapshot<KanbanConfig> {
+    return structuredClone(readConfig(this.workspaceRoot)) as ReadonlySnapshot<KanbanConfig>
+  }
+
   // --- Board resolution helpers ---
 
   /** @internal */

package/src/sdk/__tests__/KanbanSDK.test.ts

@@ -155,6 +155,62 @@ describe('KanbanSDK', () => {
     })
   })
 
+  describe('getConfigSnapshot', () => {
+    it('returns an isolated clone that cannot mutate subsequent SDK reads or persisted config', () => {
+      writeWorkspaceConfig(workspaceDir, {
+        defaultBoard: 'default',
+        kanbanDirectory: '.kanban',
+        boards: {
+          default: {
+            name: 'Default',
+            columns: [{ id: 'backlog', name: 'Backlog' }],
+            nextCardId: 1,
+            defaultStatus: 'backlog',
+            defaultPriority: 'medium',
+          },
+        },
+        plugins: {
+          'auth.identity': {
+            provider: 'kl-auth-plugin',
+            options: {
+              users: [{ username: 'alice', password: '$2b$12$existing-hash' }],
+            },
+          },
+        },
+        webhooks: [
+          { id: 'wh_snapshot', url: 'https://example.com/original', events: ['*'], active: true },
+        ],
+      })
+
+      const firstSnapshot = sdk.getConfigSnapshot() as any
+      firstSnapshot.defaultBoard = 'mutated-board'
+      firstSnapshot.boards.default.name = 'Mutated Board'
+      firstSnapshot.webhooks[0].url = 'https://example.com/mutated'
+      firstSnapshot.plugins['auth.identity'].options.users.push({ username: 'mallory', password: 'bad-hash' })
+
+      const secondSnapshot = sdk.getConfigSnapshot() as any
+      const persisted = JSON.parse(fs.readFileSync(path.join(workspaceDir, '.kanban.json'), 'utf-8')) as any
+
+      expect(secondSnapshot.defaultBoard).toBe('default')
+      expect(secondSnapshot.boards.default.name).toBe('Default')
+      expect(secondSnapshot.webhooks[0].url).toBe('https://example.com/original')
+      expect(secondSnapshot.plugins['auth.identity'].options.users).toEqual([
+        { username: 'alice', password: '$2b$12$existing-hash' },
+      ])
+      expect(sdk.listWebhooks()).toEqual([
+        { id: 'wh_snapshot', url: 'https://example.com/original', events: ['*'], active: true },
+      ])
+      expect(persisted.defaultBoard).toBe('default')
+      expect(persisted.boards.default.name).toBe('Default')
+      expect(persisted.webhooks).toEqual([
+        { id: 'wh_snapshot', url: 'https://example.com/original', events: ['*'], active: true },
+      ])
+      expect(persisted.plugins['auth.identity'].options.users).toEqual([
+        { username: 'alice', password: '$2b$12$existing-hash' },
+      ])
+    })
+  })
+
   describe('getCardStateStatus', () => {
     it('reports builtin backend status and allows the default actor when auth.identity is noop', () => {
       const status = sdk.getCardStateStatus()
@@ -1080,10 +1136,18 @@ describe('KanbanSDK', () => {
       expect(reloaded?.actions).toBeUndefined()
     })
 
-    it('should throw if no actionWebhookUrl is configured', async () => {
+    it('should append an activity log entry even when no actionWebhookUrl is configured', async () => {
       await sdk.init()
       const card = await sdk.createCard({ content: '# Card', actions: ['retry'] })
-      await expect(sdk.triggerAction(card.id, 'retry')).rejects.toThrow('No action webhook URL configured')
+      await expect(sdk.triggerAction(card.id, 'retry')).resolves.toBeUndefined()
+
+      const logs = await sdk.listLogs(card.id)
+      expect(logs).toHaveLength(1)
+      expect(logs[0]).toMatchObject({
+        source: 'system',
+        text: 'Action triggered: `retry`',
+        object: { action: 'retry' },
+      })
     })
 
     it('should throw if card not found', async () => {
@@ -1094,45 +1158,36 @@ describe('KanbanSDK', () => {
       await expect(sdk.triggerAction('nonexistent', 'retry')).rejects.toThrow('Card not found')
     })
 
-    it('should POST correct payload to actionWebhookUrl on success', async () => {
+    it('should not call fetch directly; webhook delivery is delegated to plugin after-events', async () => {
       await sdk.init()
       const card = await sdk.createCard({ content: '# My Card', actions: ['retry'] })
 
-      const { readConfig, writeConfig } = await import('../../shared/config')
-      const config = readConfig(sdk.workspaceRoot)
-      writeConfig(sdk.workspaceRoot, { ...config, actionWebhookUrl: 'https://example.com/webhook' })
-
       const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: 'OK' })
       vi.stubGlobal('fetch', mockFetch)
 
       await sdk.triggerAction(card.id, 'retry')
 
-      expect(mockFetch).toHaveBeenCalledOnce()
-      const [url, init] = mockFetch.mock.calls[0]
-      expect(url).toBe('https://example.com/webhook')
-      expect(init.method).toBe('POST')
-      expect(init.headers).toEqual({ 'Content-Type': 'application/json' })
-      const body = JSON.parse(init.body)
-      expect(body.action).toBe('retry')
-      expect(body.board).toBe('default')
-      expect(body.list).toBe(card.status)
-      expect(body.card.id).toBe(card.id)
-      expect(body.card.filePath).toBeUndefined()
+      expect(mockFetch).not.toHaveBeenCalled()
+
+      const logs = await sdk.listLogs(card.id)
+      expect(logs.at(-1)).toMatchObject({
+        text: 'Action triggered: `retry`',
+        object: { action: 'retry' },
+      })
 
       vi.unstubAllGlobals()
     })
 
-    it('should throw on non-2xx webhook response', async () => {
+    it('should stay side-effect free with respect to direct webhook transport failures', async () => {
       await sdk.init()
       const card = await sdk.createCard({ content: '# My Card', actions: ['retry'] })
 
-      const { readConfig, writeConfig } = await import('../../shared/config')
-      const config = readConfig(sdk.workspaceRoot)
-      writeConfig(sdk.workspaceRoot, { ...config, actionWebhookUrl: 'https://example.com/webhook' })
-
       vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' }))
 
-      await expect(sdk.triggerAction(card.id, 'retry')).rejects.toThrow('Action webhook responded with 500')
+      await expect(sdk.triggerAction(card.id, 'retry')).resolves.toBeUndefined()
+
+      const logs = await sdk.listLogs(card.id)
+      expect(logs.at(-1)?.text).toBe('Action triggered: `retry`')
 
       vi.unstubAllGlobals()
     })

package/src/sdk/plugins/index.d.ts

@@ -337,6 +337,13 @@ export type StandaloneHttpHandler = (request: StandaloneHttpRequestContext) => P
  * resolved the active workspace capability selections.
  */
 export interface StandaloneHttpPluginRegistrationOptions {
+    /**
+     * Active SDK instance backing the standalone runtime, when provided by the host.
+     *
+     * Plugin registration code may use the full public {@link KanbanSDK} surface,
+     * including `getConfigSnapshot()`, when this seam is available.
+     */
+    readonly sdk?: KanbanSDK;
     /** Absolute workspace root containing `.kanban.json`. */
     readonly workspaceRoot: string;
     /** Absolute workspace `.kanban` directory. */

package/src/sdk/plugins/index.ts

@@ -623,6 +623,13 @@ export type StandaloneHttpHandler = (request: StandaloneHttpRequestContext) => P
  * resolved the active workspace capability selections.
  */
 export interface StandaloneHttpPluginRegistrationOptions {
+  /**
+   * Active SDK instance backing the standalone runtime, when provided by the host.
+   *
+   * Plugin registration code may use the full public {@link KanbanSDK} surface,
+   * including `getConfigSnapshot()`, when this seam is available.
+   */
+  readonly sdk?: KanbanSDK
   /** Absolute workspace root containing `.kanban.json`. */
   readonly workspaceRoot: string
   /** Absolute workspace `.kanban` directory. */