@kernel.chat/kbot 4.1.1 → 4.4.0

package/dist/adapters/peekaboo/types.d.ts

@@ -0,0 +1,69 @@
+export interface PeekabooFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PeekabooElement {
+    /** Element handle, e.g. "B1" (button), "T1" (text field). */
+    id: string;
+    role: string;
+    label?: string;
+    frame: PeekabooFrame;
+    /** Whether the element accepts a value (text fields, sliders, etc.). */
+    settable?: boolean;
+    /** Action names the element advertises via the AX API. */
+    named_actions?: string[];
+}
+export interface PeekabooSeeResult {
+    /** Snapshot id used by subsequent `--snapshot $id` arguments. */
+    snapshot: string;
+    app?: string;
+    window?: string;
+    elements: PeekabooElement[];
+    /** Optional path on disk where the screenshot was written. */
+    screenshot_path?: string;
+}
+export interface PeekabooClickResult {
+    ok: boolean;
+    target?: string;
+    coords?: [number, number];
+}
+export interface PeekabooTypeResult {
+    ok: boolean;
+    typed: string;
+    cleared?: boolean;
+}
+export interface PeekabooSetValueResult {
+    ok: boolean;
+    target: string;
+    value: string;
+}
+export interface PeekabooPerformActionResult {
+    ok: boolean;
+    target: string;
+    action: string;
+}
+export interface PeekabooAgentResult {
+    ok: boolean;
+    output: string;
+}
+/**
+ * Structured error returned by all command helpers when the binary exits
+ * non-zero or emits malformed JSON. Helpers return `{ ok: false, error }`
+ * rather than throw so callers can route via discriminated unions.
+ */
+export interface PeekabooError {
+    ok: false;
+    error: {
+        code: 'non-zero-exit' | 'malformed-json' | 'binary-missing' | 'unknown';
+        message: string;
+        stderr?: string;
+        stdout?: string;
+        exitCode?: number;
+    };
+}
+export type PeekabooOutcome<T> = ({
+    ok: true;
+} & T) | PeekabooError;
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/peekaboo/types.js

@@ -0,0 +1,8 @@
+// Peekaboo CLI surface — minimal type model.
+//
+// Mirrors the JSON shape emitted by the `peekaboo` macOS CLI
+// (https://github.com/openclaw/Peekaboo) without taking a runtime
+// dependency. kbot stays binary-agnostic; this adapter only ever
+// speaks JSON across the process boundary.
+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/computer.js

@@ -17,7 +17,19 @@ import { join } from 'node:path';
 import { readFileSync, unlinkSync, existsSync, mkdirSync, rmSync } from 'node:fs';
 import { registerTool } from './index.js';
 import { Coordinator } from '../computer-use-coordinator.js';
+import { peekabooAvailable, see as peekabooSee, click as peekabooClick, type_ as peekabooType, } from '../adapters/peekaboo/index.js';
 const platform = process.platform;
+// ── Peekaboo AX-first fallback ───────────────────────────────────
+// When the peekaboo CLI is installed, try AX-aware automation before
+// synthetic input. Cached at module-load, refreshed if env hint changes.
+let _peekabooReady = null;
+function peekabooReady() {
+    if (process.env.KBOT_DISABLE_PEEKABOO === '1')
+        return Promise.resolve(false);
+    if (!_peekabooReady)
+        _peekabooReady = peekabooAvailable().catch(() => false);
+    return _peekabooReady;
+}
 const LOCK_DIR = join(homedir(), '.kbot');
 // Legacy single-session lock path. Retained as a constant for back-compat
 // with any callers that referenced it; the actual locking is now performed
@@ -485,6 +497,27 @@ export function registerComputerTools() {
                 return 'Error: x and y must be numbers';
             }
             try {
+                // AX-first fallback: when peekaboo is on PATH, try AX-aware click
+                // before synthetic input. Falls through to AppleScript+cliclick on
+                // any failure so existing behavior is preserved.
+                if (platform === 'darwin' && app && await peekabooReady()) {
+                    try {
+                        const snap = await peekabooSee({ app });
+                        if (snap.ok) {
+                            const target = (args.element_id ?? args.label ?? null);
+                            if (target) {
+                                const result = await peekabooClick({
+                                    snapshot: snap.snapshot,
+                                    on: String(target),
+                                });
+                                if (result.ok)
+                                    return `clicked via AX: ${target}`;
+                                // fall through to synthetic on AX failure
+                            }
+                        }
+                    }
+                    catch { /* fall through */ }
+                }
                 if (platform === 'darwin') {
                     try {
                         if (button === 'double') {
@@ -712,6 +745,21 @@ export function registerComputerTools() {
                 const text = String(args.text);
                 if (!text)
                     return 'Error: text is required';
+                // AX-first fallback: when peekaboo is on PATH, try AX-aware typing
+                // before synthetic keystrokes. Falls through to AppleScript on any
+                // failure so existing behavior is preserved.
+                if (platform === 'darwin' && await peekabooReady()) {
+                    try {
+                        const clear = args.clear === true;
+                        const delayMs = typeof args.delayMs === 'number' ? args.delayMs : undefined;
+                        const result = await peekabooType({ text, clear, delayMs });
+                        if (result.ok) {
+                            return `Typed via AX: ${text.slice(0, 80)}${text.length > 80 ? '...' : ''}`;
+                        }
+                        // fall through to synthetic on AX failure
+                    }
+                    catch { /* fall through */ }
+                }
                 if (platform === 'darwin') {
                     const escaped = escapeAppleScript(text);
                     try {
@@ -1104,5 +1152,21 @@ export function registerComputerTools() {
             return `Computer use session ended.${releasedNote}`;
         },
     });
+    // ── Peekaboo status (AX-first diagnostics) ──
+    registerTool({
+        name: 'peekaboo_status',
+        description: 'Report whether the AX-first peekaboo CLI is available on PATH for accessibility-aware automation.',
+        parameters: {},
+        tier: 'free',
+        async execute() {
+            if (process.env.KBOT_DISABLE_PEEKABOO === '1') {
+                return 'AX-first unavailable (disabled via KBOT_DISABLE_PEEKABOO=1)';
+            }
+            const ready = await peekabooReady();
+            return ready
+                ? 'AX-first available via peekaboo'
+                : 'AX-first unavailable (peekaboo CLI not on PATH)';
+        },
+    });
 }
 //# sourceMappingURL=computer.js.map

package/dist/tools/peekaboo.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from './index.js';
+export declare const peekabooTools: readonly ToolDefinition[];
+export declare function registerPeekabooTools(): void;
+//# sourceMappingURL=peekaboo.d.ts.map