@kernel.chat/kbot 4.1.1 → 4.3.0

package/dist/adapters/agent-sdk/from-agent-sdk.d.ts

@@ -0,0 +1,28 @@
+import type { ToolDefinition } from '../../tools/index.js';
+import type { AgentSdkExecutableTool, AgentSdkTool } from './types.js';
+export interface FromAgentSdkOptions {
+    /** kbot tier to assign to the imported tool. Default 'free'. */
+    tier?: ToolDefinition['tier'];
+    /** Custom timeout (ms). */
+    timeout?: number;
+    /** Max result size (bytes). */
+    maxResultSize?: number;
+    /**
+     * Fallback executor when the source tool ships no handler. Useful when the
+     * caller routes execution elsewhere (e.g., back through the Anthropic SDK).
+     */
+    fallbackExecutor?: (toolName: string, args: Record<string, unknown>) => Promise<string> | string;
+}
+/**
+ * Convert a non-executable Agent SDK tool definition into a kbot ToolDefinition.
+ * Because the source has no handler, an executor must be supplied via opts.fallbackExecutor
+ * — otherwise the resulting tool will return a structured "no handler" error string when invoked.
+ */
+export declare function fromAgentSdkTool(tool: AgentSdkTool, opts?: FromAgentSdkOptions): ToolDefinition;
+/**
+ * Convert an executable Agent SDK tool (schema + handler) into a kbot ToolDefinition.
+ * Preferred over fromAgentSdkTool() when the caller has the implementation in process.
+ */
+export declare function fromAgentSdkExecutableTool(tool: AgentSdkExecutableTool, opts?: Omit<FromAgentSdkOptions, 'fallbackExecutor'>): ToolDefinition;
+export declare function fromAgentSdkTools(tools: AgentSdkTool[], opts?: FromAgentSdkOptions): ToolDefinition[];
+//# sourceMappingURL=from-agent-sdk.d.ts.map

package/dist/adapters/agent-sdk/from-agent-sdk.js

@@ -0,0 +1,107 @@
+// Anthropic Agent SDK tool → kbot ToolDefinition
+//
+// Lets a kbot host import third-party Agent SDK tools (or hand-written
+// schema/handler pairs) and register them in the kbot tool registry. Schema
+// is downconverted from JSON Schema to kbot's flatter parameter shape.
+//
+// Inverse of to-agent-sdk.ts. Round-trip is lossy in general (JSON Schema is
+// strictly richer than kbot's shape), but is stable for the param shapes
+// that kbot itself uses.
+const JSON_TO_KBOT = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    boolean: 'boolean',
+    object: 'object',
+    array: 'array',
+    null: 'null',
+};
+function pickType(t) {
+    if (typeof t === 'string')
+        return JSON_TO_KBOT[t] ?? 'string';
+    if (Array.isArray(t)) {
+        // Pick the first non-null type to keep parity with kbot's single-type shape.
+        const first = t.find((x) => x !== 'null');
+        return first ? JSON_TO_KBOT[first] ?? 'string' : 'string';
+    }
+    return 'string';
+}
+function mapProperty(p, required) {
+    const out = {
+        type: pickType(p.type),
+        description: typeof p.description === 'string' ? p.description : '',
+        required,
+    };
+    if (p.default !== undefined)
+        out.default = p.default;
+    if (p.items !== undefined)
+        out.items = p.items;
+    if (p.properties)
+        out.properties = p.properties;
+    return out;
+}
+function buildParameters(schema) {
+    if (!schema || typeof schema !== 'object')
+        return {};
+    const required = new Set(schema.required ?? []);
+    const out = {};
+    for (const [name, prop] of Object.entries(schema.properties ?? {})) {
+        out[name] = mapProperty(prop, required.has(name));
+    }
+    return out;
+}
+/**
+ * Convert a non-executable Agent SDK tool definition into a kbot ToolDefinition.
+ * Because the source has no handler, an executor must be supplied via opts.fallbackExecutor
+ * — otherwise the resulting tool will return a structured "no handler" error string when invoked.
+ */
+export function fromAgentSdkTool(tool, opts = {}) {
+    const fallback = opts.fallbackExecutor;
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: buildParameters(tool.input_schema),
+        tier: opts.tier ?? 'free',
+        timeout: opts.timeout,
+        maxResultSize: opts.maxResultSize,
+        async execute(args) {
+            if (fallback) {
+                try {
+                    const result = await fallback(tool.name, args);
+                    return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+                }
+                catch (e) {
+                    return `Error: ${e.message}`;
+                }
+            }
+            return `Error: tool "${tool.name}" was imported without a handler. Provide opts.fallbackExecutor when calling fromAgentSdkTool().`;
+        },
+    };
+}
+/**
+ * Convert an executable Agent SDK tool (schema + handler) into a kbot ToolDefinition.
+ * Preferred over fromAgentSdkTool() when the caller has the implementation in process.
+ */
+export function fromAgentSdkExecutableTool(tool, opts = {}) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: buildParameters(tool.input_schema),
+        tier: opts.tier ?? 'free',
+        timeout: opts.timeout,
+        maxResultSize: opts.maxResultSize,
+        async execute(args) {
+            try {
+                const result = await tool.handler(args);
+                return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            }
+            catch (e) {
+                return `Error: ${e.message}`;
+            }
+        },
+    };
+}
+export function fromAgentSdkTools(tools, opts = {}) {
+    return tools.map((t) => fromAgentSdkTool(t, opts));
+}
+//# sourceMappingURL=from-agent-sdk.js.map

package/dist/adapters/agent-sdk/index.d.ts

@@ -0,0 +1,4 @@
+export type { AgentSdkTool, AgentSdkExecutableTool, AgentSdkInputSchema, JsonSchemaProperty, JsonSchemaType, } from './types.js';
+export { toAgentSdkTool, toAgentSdkTools, type ToAgentSdkOptions, } from './to-agent-sdk.js';
+export { fromAgentSdkTool, fromAgentSdkExecutableTool, fromAgentSdkTools, type FromAgentSdkOptions, } from './from-agent-sdk.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/agent-sdk/index.js

@@ -0,0 +1,14 @@
+// Anthropic Agent SDK adapter — bidirectional schema translation between
+// kbot's ToolDefinition surface and the Agent SDK / Messages API tool surface.
+//
+// kbot stays provider-agnostic — this adapter takes no runtime dependency
+// on @anthropic-ai/sdk. It only translates schemas and (for the from-side)
+// wraps optional executors. Round-trip kbot → Agent SDK → kbot is stable
+// for the parameter shapes kbot itself uses.
+//
+// Background: with the Anthropic Agent SDK opening to external developers
+// in May 2026, kbot tools can now be advertised to that ecosystem and
+// vice-versa — without coupling the registry to one provider's runtime.
+export { toAgentSdkTool, toAgentSdkTools, } from './to-agent-sdk.js';
+export { fromAgentSdkTool, fromAgentSdkExecutableTool, fromAgentSdkTools, } from './from-agent-sdk.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/agent-sdk/to-agent-sdk.d.ts

@@ -0,0 +1,13 @@
+import type { ToolDefinition } from '../../tools/index.js';
+import type { AgentSdkTool } from './types.js';
+export interface ToAgentSdkOptions {
+    /** If true (default), kbot tool names are passed through unchanged. */
+    preserveName?: boolean;
+    /** Optional rename hook. Wins over preserveName. */
+    renameTool?: (name: string) => string;
+    /** If true, pass `additionalProperties: false` on the input schema. Default true. */
+    strict?: boolean;
+}
+export declare function toAgentSdkTool(tool: ToolDefinition, opts?: ToAgentSdkOptions): AgentSdkTool;
+export declare function toAgentSdkTools(tools: ToolDefinition[], opts?: ToAgentSdkOptions): AgentSdkTool[];
+//# sourceMappingURL=to-agent-sdk.d.ts.map

package/dist/adapters/agent-sdk/to-agent-sdk.js

@@ -0,0 +1,73 @@
+// kbot ToolDefinition → Anthropic Agent SDK tool
+//
+// One-way schema translation. The Agent SDK delivers tool_use blocks and
+// expects the host to route them to a handler — that routing belongs in the
+// caller's agent loop, not in the adapter. This file only produces the
+// schema half so kbot tools can be advertised to the Agent SDK / Messages
+// API without taking a runtime dependency on @anthropic-ai/sdk.
+const KBOT_TYPE_TO_JSON = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    boolean: 'boolean',
+    object: 'object',
+    array: 'array',
+    null: 'null',
+};
+function mapType(t) {
+    const lc = t.toLowerCase();
+    return KBOT_TYPE_TO_JSON[lc] ?? 'string';
+}
+function mapParameter(p) {
+    const out = {
+        type: mapType(p.type),
+        description: p.description,
+    };
+    if (p.default !== undefined)
+        out.default = p.default;
+    if (p.items)
+        out.items = p.items;
+    if (p.properties) {
+        const nested = {};
+        for (const [k, v] of Object.entries(p.properties)) {
+            // Best-effort: nested properties in kbot params are loosely typed.
+            const vv = v;
+            nested[k] = {
+                type: vv.type ? mapType(vv.type) : 'string',
+                description: vv.description ?? '',
+            };
+        }
+        out.properties = nested;
+    }
+    return out;
+}
+export function toAgentSdkTool(tool, opts = {}) {
+    const properties = {};
+    const required = [];
+    for (const [name, param] of Object.entries(tool.parameters)) {
+        properties[name] = mapParameter(param);
+        if (param.required)
+            required.push(name);
+    }
+    const input_schema = {
+        type: 'object',
+        properties,
+        additionalProperties: opts.strict === false ? true : false,
+    };
+    if (required.length > 0)
+        input_schema.required = required;
+    const name = opts.renameTool
+        ? opts.renameTool(tool.name)
+        : opts.preserveName === false
+            ? tool.name.replace(/[^A-Za-z0-9_-]/g, '_')
+            : tool.name;
+    return {
+        name,
+        description: tool.description,
+        input_schema,
+    };
+}
+export function toAgentSdkTools(tools, opts = {}) {
+    return tools.map((t) => toAgentSdkTool(t, opts));
+}
+//# sourceMappingURL=to-agent-sdk.js.map

package/dist/adapters/agent-sdk/types.d.ts

@@ -0,0 +1,41 @@
+export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+export interface JsonSchemaProperty {
+    type?: JsonSchemaType | JsonSchemaType[];
+    description?: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty | Record<string, unknown>;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    default?: unknown;
+    [k: string]: unknown;
+}
+export interface AgentSdkInputSchema {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/**
+ * The on-the-wire tool definition the Agent SDK and the Messages API both
+ * accept. Names are snake_case by convention; the SDK does not enforce.
+ */
+export interface AgentSdkTool {
+    name: string;
+    description: string;
+    input_schema: AgentSdkInputSchema;
+}
+/**
+ * Optional executable companion. The SDK delivers `tool_use` blocks; the
+ * caller is responsible for routing them to a handler. `AgentSdkExecutableTool`
+ * couples the schema with a handler so the from-adapter can hand back something
+ * the kbot registry can run.
+ */
+export interface AgentSdkExecutableTool extends AgentSdkTool {
+    /**
+     * Handler may return a string (passed through) or arbitrary JSON-serializable
+     * value (stringified by the adapter). Mirrors what real Agent SDK handlers
+     * return in practice.
+     */
+    handler: (input: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/agent-sdk/types.js

@@ -0,0 +1,9 @@
+// Anthropic Agent SDK tool surface — minimal type model.
+//
+// Mirrors the Tool shape used by @anthropic-ai/sdk and the Agent SDK
+// without taking a runtime dependency. kbot stays provider-agnostic;
+// this adapter only ever speaks JSON Schema and JSON.
+//
+// Reference: https://docs.anthropic.com/en/api/messages#tools
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli.js

@@ -56,6 +56,7 @@ async function main() {
         .option('--lite', 'Lightweight mode — skip heavy tools (auto-enabled on Replit)')
         .option('--safe', 'Confirm destructive operations')
         .option('--strict', 'Confirm ALL operations')
+        .option('--persona <id>', 'Scope tool access to a persona (researcher, coder, computer-use)')
         .option('--ollama-launch', 'Auto-configure for ollama launch (sets Ollama as provider)')
         .argument('[prompt...]', 'One-shot prompt')
         .helpOption('-h, --help', 'display help for command')
@@ -4369,7 +4370,7 @@ async function main() {
     }
     // Permission mode: autonomous by default, users opt-in to confirmations
     {
-        const { setPermissionMode } = await import('./permissions.js');
+        const { setPermissionMode, setActivePersona } = await import('./permissions.js');
         if (opts.yes) {
             // --yes / -y: skip all confirmations (for scripts & CI)
             setPermissionMode('permissive');
@@ -4384,6 +4385,19 @@ async function main() {
             // DEFAULT: permissive — kbot acts autonomously, no confirmation prompts
             setPermissionMode('permissive');
         }
+        // Persona scoping (v4.2.0). Optional. Falls back to env var.
+        const personaId = opts.persona || process.env.KBOT_PERSONA || null;
+        if (personaId) {
+            try {
+                setActivePersona(personaId);
+                if (!opts.quiet && !opts.pipe)
+                    printInfo(`Persona: ${personaId}`);
+            }
+            catch (err) {
+                printError(err.message);
+                process.exit(1);
+            }
+        }
     }
     // Register built-in agents (hacker, operator, dreamer) so --agent flag works
     registerBuiltinAgents();

package/dist/permissions.d.ts

@@ -1,4 +1,21 @@
+import { type Persona } from './futures/persona/index.js';
 export type PermissionMode = 'permissive' | 'normal' | 'strict';
+/**
+ * Set (or clear) the active persona by id. Pass null to disable persona checking.
+ * Throws if id is not found in PERSONA_REGISTRY.
+ *
+ * v4.2.0 wires the futures/persona substrate into the live permissions chain.
+ * When a persona is set, every checkPermission() call runs canInvoke() FIRST;
+ * if the persona denies, the tool is blocked before the destructive-op prompt.
+ */
+export declare function setActivePersona(id: string | null): void;
+/** Get the currently active persona, or null if none. */
+export declare function getActivePersona(): Persona | null;
+/**
+ * Check the active persona (if any) against a tool invocation.
+ * Returns the denial reason string if denied, or null if allowed (or no persona set).
+ */
+export declare function checkPersonaScope(toolName: string, args: Record<string, unknown>): string | null;
 /** Set the permission mode */
 export declare function setPermissionMode(mode: PermissionMode): void;
 /** Get the current permission mode */

package/dist/permissions.js

@@ -13,7 +13,46 @@
 //   'strict'      — confirm all file writes and tool calls
 import { createInterface } from 'node:readline';
 import chalk from 'chalk';
+import { canInvoke, PERSONA_REGISTRY, } from './futures/persona/index.js';
 let currentMode = 'normal';
+/** Active persona for this CLI run. null = no persona-scoping (default). */
+let activePersona = null;
+/**
+ * Set (or clear) the active persona by id. Pass null to disable persona checking.
+ * Throws if id is not found in PERSONA_REGISTRY.
+ *
+ * v4.2.0 wires the futures/persona substrate into the live permissions chain.
+ * When a persona is set, every checkPermission() call runs canInvoke() FIRST;
+ * if the persona denies, the tool is blocked before the destructive-op prompt.
+ */
+export function setActivePersona(id) {
+    if (id === null) {
+        activePersona = null;
+        return;
+    }
+    const persona = PERSONA_REGISTRY[id];
+    if (!persona) {
+        const known = Object.keys(PERSONA_REGISTRY).join(', ');
+        throw new Error(`unknown persona "${id}". Known personas: ${known}`);
+    }
+    activePersona = persona;
+}
+/** Get the currently active persona, or null if none. */
+export function getActivePersona() {
+    return activePersona;
+}
+/**
+ * Check the active persona (if any) against a tool invocation.
+ * Returns the denial reason string if denied, or null if allowed (or no persona set).
+ */
+export function checkPersonaScope(toolName, args) {
+    if (!activePersona)
+        return null;
+    const verdict = canInvoke(activePersona, toolName, args);
+    if (verdict.allowed)
+        return null;
+    return `Persona '${activePersona.id}' denies '${toolName}': ${verdict.reason ?? 'permission denied'}`;
+}
 /** Patterns that always require confirmation in normal mode */
 const DESTRUCTIVE_PATTERNS = [
     { pattern: /^git\s+push/i, reason: 'Pushes code to remote — visible to others' },
@@ -119,6 +158,15 @@ export async function confirmToolCall(toolName, args, reason) {
  * Used as middleware in the tool execution pipeline.
  */
 export async function checkPermission(toolName, args) {
+    // Persona check fires BEFORE the destructive-op prompt. If a persona is
+    // set and denies the tool, fail fast — no confirmation prompt, no retry.
+    const personaDenial = checkPersonaScope(toolName, args);
+    if (personaDenial) {
+        console.log();
+        console.log(`  ${chalk.red('✗')} ${personaDenial}`);
+        console.log();
+        return false;
+    }
     const reason = needsConfirmation(toolName, args);
     if (!reason)
         return true;

package/dist/tool-pipeline.js

@@ -11,6 +11,7 @@
 //   pipeline.use(metricsMiddleware(recordMetrics))
 //   pipeline.use(executionMiddleware(executeTool))
 //   await pipeline.execute(ctx)
+import { checkPersonaScope } from './permissions.js';
 export class ToolPipeline {
     middleware = [];
     /** Append middleware to the end of the pipeline */
@@ -56,6 +57,16 @@ export class ToolPipeline {
  */
 export function permissionMiddleware(checkPermission) {
     return async (ctx, next) => {
+        // v4.2.0: persona scope check fires BEFORE the destructive-op
+        // confirmation. A persona denial blocks the tool with a clear reason
+        // and is non-interactive — no prompt, no retry.
+        const personaDenial = checkPersonaScope(ctx.toolName, ctx.toolArgs);
+        if (personaDenial) {
+            ctx.aborted = true;
+            ctx.abortReason = personaDenial;
+            ctx.error = personaDenial;
+            return;
+        }
         const allowed = await checkPermission(ctx.toolName, ctx.toolArgs);
         if (!allowed) {
             ctx.aborted = true;

package/dist/tools/security-audit-local.d.ts

@@ -0,0 +1,47 @@
+import type { ToolDefinition } from './index.js';
+type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFO';
+export interface SurfaceSignal {
+    id: string;
+    category: string;
+    severity: Severity;
+    file: string;
+    line: number;
+    excerpt: string;
+    pattern: string;
+    ts: number;
+}
+export interface SurfaceMap {
+    sessionId: string;
+    target: string;
+    startedAt: number;
+    filesWalked: number;
+    bytesRead: number;
+    signals: SurfaceSignal[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+}
+export interface BuildSurfaceMapOptions {
+    target: string;
+    excludes?: Iterable<string>;
+    severityFloor?: Severity;
+    sessionId?: string;
+}
+export declare function buildSurfaceMap(opts: BuildSurfaceMapOptions): SurfaceMap;
+export declare function persistSurfaceMap(map: SurfaceMap, baseDir?: string): string;
+export declare function renderSurfaceMap(map: SurfaceMap, persistedTo: string): string;
+export interface RunOptions {
+    target: string;
+    severityFloor?: Severity;
+    excludes?: string[];
+    baseDir?: string;
+}
+export declare function runSecurityAuditLocal(opts: RunOptions): {
+    map: SurfaceMap;
+    persistedTo: string;
+    markdown: string;
+};
+export declare const securityAuditLocalTool: ToolDefinition;
+export {};
+//# sourceMappingURL=security-audit-local.d.ts.map