@kernel.chat/kbot 3.99.31 → 3.99.33

package/dist/tools/workspace-agent-tools.js

@@ -0,0 +1,191 @@
+/**
+ * Workspace Agent kbot tool definitions.
+ *
+ * NOT registered in tools/index.ts. Wire up via `registerWorkspaceAgentTools()`
+ * from a higher-level bootstrap once the feature is shipped.
+ *
+ * Each tool returns a string (the kbot tool contract). State persists via
+ * the WorkspaceAgent class — file at <root>/<id>.json.
+ */
+import { WorkspaceAgent, } from '../workspace-agents.js';
+function getAgent(opts) {
+    return new WorkspaceAgent(opts ?? {});
+}
+function fmt(value) {
+    if (typeof value === 'string')
+        return value;
+    return '```json\n' + JSON.stringify(value, null, 2) + '\n```';
+}
+function parseJsonArray(raw, field) {
+    if (raw === undefined || raw === null || raw === '')
+        return [];
+    if (Array.isArray(raw))
+        return raw.map(String);
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return [];
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!Array.isArray(parsed)) {
+                throw new Error(`${field} must be a JSON array`);
+            }
+            return parsed.map(String);
+        }
+        catch (e) {
+            // accept comma-separated as a convenience
+            if (!trimmed.startsWith('[')) {
+                return trimmed
+                    .split(',')
+                    .map(s => s.trim())
+                    .filter(Boolean);
+            }
+            throw e;
+        }
+    }
+    throw new Error(`${field} must be a string or array`);
+}
+export const workspaceAgentCreate = {
+    name: 'workspace_agent_create',
+    description: 'Create a long-running named workspace agent. Persists at ~/.kbot/workspace-agents/<id>.json. ' +
+        'Names must be unique per workspace. Permissions enforced via allowedTools whitelist + scopes.',
+    parameters: {
+        name: {
+            type: 'string',
+            description: 'Unique name for this agent in the workspace.',
+            required: true,
+        },
+        mission: {
+            type: 'string',
+            description: '1–3 sentence mission the agent will pursue across sessions.',
+            required: true,
+        },
+        allowedTools: {
+            type: 'string',
+            description: 'JSON array (or comma-separated list) of tool names this agent may invoke. Empty = no tool calls.',
+        },
+        scopes: {
+            type: 'string',
+            description: 'JSON array (or comma-separated list) of capability scopes, e.g. ["read:files","write:tools","invoke:slack"].',
+        },
+    },
+    tier: 'free',
+    async execute(args) {
+        try {
+            const allowedTools = parseJsonArray(args.allowedTools, 'allowedTools');
+            const scopes = parseJsonArray(args.scopes, 'scopes');
+            const result = await getAgent().create({
+                name: String(args.name),
+                mission: String(args.mission),
+                allowedTools,
+                scopes,
+            });
+            return fmt({ created: result });
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};
+export const workspaceAgentStart = {
+    name: 'workspace_agent_start',
+    description: 'Start a workspace agent on a task. Transitions status to "running", invokes the planner, persists tool calls into history.',
+    parameters: {
+        agentId: { type: 'string', description: 'Agent id from create.', required: true },
+        taskInput: {
+            type: 'string',
+            description: 'Task prompt to plan and execute.',
+            required: true,
+        },
+    },
+    tier: 'free',
+    async execute(args) {
+        try {
+            const result = await getAgent().start(String(args.agentId), String(args.taskInput));
+            return fmt({ started: result });
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};
+export const workspaceAgentResume = {
+    name: 'workspace_agent_resume',
+    description: 'Resume a paused or failed workspace agent. Loads state from disk and transitions to running.',
+    parameters: {
+        agentId: { type: 'string', description: 'Agent id.', required: true },
+    },
+    tier: 'free',
+    async execute(args) {
+        try {
+            const state = await getAgent().resume(String(args.agentId));
+            return fmt({
+                resumed: { id: state.id, name: state.name, status: state.status },
+            });
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};
+export const workspaceAgentStatus = {
+    name: 'workspace_agent_status',
+    description: 'Get full state for a workspace agent (status, history, plan).',
+    parameters: {
+        agentId: { type: 'string', description: 'Agent id.', required: true },
+    },
+    tier: 'free',
+    async execute(args) {
+        try {
+            const state = await getAgent().status(String(args.agentId));
+            return fmt(state);
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};
+export const workspaceAgentStop = {
+    name: 'workspace_agent_stop',
+    description: 'Stop a running workspace agent. Transitions status to "paused".',
+    parameters: {
+        agentId: { type: 'string', description: 'Agent id.', required: true },
+    },
+    tier: 'free',
+    async execute(args) {
+        try {
+            const state = await getAgent().stop(String(args.agentId));
+            return fmt({
+                stopped: { id: state.id, name: state.name, status: state.status },
+            });
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};
+export const workspaceAgentList = {
+    name: 'workspace_agent_list',
+    description: 'List all workspace agents in this workspace.',
+    parameters: {},
+    tier: 'free',
+    async execute() {
+        try {
+            const list = await getAgent().list();
+            return fmt({ agents: list, count: list.length });
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};
+/** Convenience array — caller can iterate to register all six. */
+export const workspaceAgentTools = [
+    workspaceAgentCreate,
+    workspaceAgentStart,
+    workspaceAgentResume,
+    workspaceAgentStatus,
+    workspaceAgentStop,
+    workspaceAgentList,
+];
+//# sourceMappingURL=workspace-agent-tools.js.map

package/dist/workspace-agents.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Workspace Agents — long-running named agents bound to a workspace with
+ * permissions and resumable state. Parity with OpenAI's Workspace Agents
+ * (Apr 2026). Wraps the hierarchical planner at ./planner/hierarchical/.
+ *
+ * State JSON shape (one file per agent at <root>/<id>.json):
+ *   { id, name, mission, allowedTools, scopes, status, createdAt, updatedAt,
+ *     currentPlanId?, history: [{ ts, event, data }] }
+ *
+ * Storage root: process.env.KBOT_WORKSPACE_AGENTS_ROOT
+ *               ?? <homedir>/.kbot/workspace-agents
+ *
+ * Permissions: every tool invocation must pass through `gate(toolName)` which
+ * checks `allowedTools`. Scopes are recorded but enforcement is per-tool via
+ * the allowedTools whitelist.
+ */
+import type { AgentOptions } from './agent.js';
+export type WorkspaceAgentStatus = 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+export type Scope = string;
+export interface HistoryEvent {
+    ts: string;
+    event: string;
+    data?: unknown;
+}
+export interface WorkspaceAgentState {
+    id: string;
+    name: string;
+    mission: string;
+    allowedTools: string[];
+    scopes: Scope[];
+    status: WorkspaceAgentStatus;
+    createdAt: string;
+    updatedAt: string;
+    currentPlanId?: string;
+    history: HistoryEvent[];
+}
+export interface CreateOptions {
+    name: string;
+    mission: string;
+    allowedTools?: string[];
+    scopes?: Scope[];
+}
+export interface CreateResult {
+    id: string;
+    name: string;
+}
+export interface StartResult {
+    id: string;
+    status: WorkspaceAgentStatus;
+    planId?: string;
+    steps: unknown[];
+}
+export interface ListEntry {
+    id: string;
+    name: string;
+    status: WorkspaceAgentStatus;
+}
+export declare class ScopeError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string, message?: string);
+}
+export declare class WorkspaceAgentError extends Error {
+    constructor(message: string);
+}
+export declare function defaultRoot(): string;
+/** A single tool call surfaced by the planner, ready to be gated + recorded. */
+export interface PlannerToolCall {
+    tool: string;
+    args?: unknown;
+    result?: unknown;
+}
+export interface PlannerStartResult {
+    planId: string;
+    steps: unknown[];
+    /**
+     * Optional list of tool calls the planner produced. When present, the
+     * WorkspaceAgent will run each through `gate()` and `recordToolCall()`,
+     * capturing `tool_blocked` events for any that ScopeError out.
+     */
+    toolCalls?: PlannerToolCall[];
+    /**
+     * Free-form notes the planner wants surfaced as history events. Each entry
+     * becomes a `planner_note` event on the agent's timeline.
+     */
+    notes?: string[];
+}
+export type PlannerStartFn = (taskInput: string, state: WorkspaceAgentState, agentOpts?: AgentOptions | null) => Promise<PlannerStartResult>;
+/**
+ * Default planner adapter — implements the 3-tier strategy:
+ *
+ *   Tier 1: KBOT_PLANNER=hierarchical AND non-null agentOpts → real
+ *           HierarchicalPlanner.planAndExecute. Tool calls extracted from
+ *           the resulting Action.steps and surfaced for gating.
+ *   Tier 2: HierarchicalPlanner module loadable but no agentOpts → call
+ *           createGoal only; emit a TODO note; return early.
+ *   Tier 3: Module import fails (e.g. test env) → deterministic stub
+ *           `{ planId: 'stub', steps: [] }`.
+ *
+ * The function never throws on planner-internal failures: each tier degrades
+ * to the next so the WorkspaceAgent.start() lifecycle stays predictable.
+ */
+export declare const defaultPlannerStart: PlannerStartFn;
+export interface WorkspaceAgentOptions {
+    /** Override storage root. Defaults to env or ~/.kbot/workspace-agents. */
+    root?: string;
+    /** Override planner adapter (used by tests). */
+    plannerStart?: PlannerStartFn;
+}
+export declare class WorkspaceAgent {
+    private readonly root;
+    private readonly plannerStart;
+    constructor(opts?: WorkspaceAgentOptions);
+    create(opts: CreateOptions): Promise<CreateResult>;
+    start(agentId: string, taskInput: string, agentOpts?: AgentOptions | null): Promise<StartResult>;
+    resume(agentId: string): Promise<WorkspaceAgentState>;
+    stop(agentId: string): Promise<WorkspaceAgentState>;
+    status(agentId: string): Promise<WorkspaceAgentState>;
+    list(): Promise<ListEntry[]>;
+    /**
+     * Permission gate. Throws ScopeError if the tool isn't in allowedTools and
+     * appends a `tool_denied` event to history. On allow, appends `tool_allowed`.
+     */
+    gate(agentId: string, toolName: string): Promise<void>;
+    /**
+     * Append a tool-call record to the agent's history. Caller must call
+     * `gate()` first; this method does NOT enforce permissions.
+     */
+    recordToolCall(agentId: string, toolName: string, args: unknown, result?: unknown): Promise<void>;
+    private appendEvent;
+    private requireState;
+}
+//# sourceMappingURL=workspace-agents.d.ts.map

package/dist/workspace-agents.js

@@ -0,0 +1,379 @@
+/**
+ * Workspace Agents — long-running named agents bound to a workspace with
+ * permissions and resumable state. Parity with OpenAI's Workspace Agents
+ * (Apr 2026). Wraps the hierarchical planner at ./planner/hierarchical/.
+ *
+ * State JSON shape (one file per agent at <root>/<id>.json):
+ *   { id, name, mission, allowedTools, scopes, status, createdAt, updatedAt,
+ *     currentPlanId?, history: [{ ts, event, data }] }
+ *
+ * Storage root: process.env.KBOT_WORKSPACE_AGENTS_ROOT
+ *               ?? <homedir>/.kbot/workspace-agents
+ *
+ * Permissions: every tool invocation must pass through `gate(toolName)` which
+ * checks `allowedTools`. Scopes are recorded but enforcement is per-tool via
+ * the allowedTools whitelist.
+ */
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export class ScopeError extends Error {
+    toolName;
+    constructor(toolName, message) {
+        super(message ?? `Tool "${toolName}" is not in this agent's allowedTools`);
+        this.name = 'ScopeError';
+        this.toolName = toolName;
+    }
+}
+export class WorkspaceAgentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkspaceAgentError';
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Storage helpers
+// ─────────────────────────────────────────────────────────────────────────────
+export function defaultRoot() {
+    const env = process.env.KBOT_WORKSPACE_AGENTS_ROOT;
+    if (env && env.trim().length > 0)
+        return env;
+    return path.join(os.homedir(), '.kbot', 'workspace-agents');
+}
+async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+function statePath(root, id) {
+    return path.join(root, `${id}.json`);
+}
+async function readState(root, id) {
+    try {
+        const raw = await fs.readFile(statePath(root, id), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+}
+async function writeState(root, state) {
+    await ensureDir(root);
+    const tmp = statePath(root, state.id) + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
+    await fs.rename(tmp, statePath(root, state.id));
+}
+async function listAll(root) {
+    try {
+        const entries = await fs.readdir(root);
+        const out = [];
+        for (const e of entries) {
+            if (!e.endsWith('.json'))
+                continue;
+            try {
+                const raw = await fs.readFile(path.join(root, e), 'utf8');
+                out.push(JSON.parse(raw));
+            }
+            catch {
+                // skip corrupt entries
+            }
+        }
+        return out;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+}
+/**
+ * Default planner adapter — implements the 3-tier strategy:
+ *
+ *   Tier 1: KBOT_PLANNER=hierarchical AND non-null agentOpts → real
+ *           HierarchicalPlanner.planAndExecute. Tool calls extracted from
+ *           the resulting Action.steps and surfaced for gating.
+ *   Tier 2: HierarchicalPlanner module loadable but no agentOpts → call
+ *           createGoal only; emit a TODO note; return early.
+ *   Tier 3: Module import fails (e.g. test env) → deterministic stub
+ *           `{ planId: 'stub', steps: [] }`.
+ *
+ * The function never throws on planner-internal failures: each tier degrades
+ * to the next so the WorkspaceAgent.start() lifecycle stays predictable.
+ */
+export const defaultPlannerStart = async (taskInput, state, agentOpts) => {
+    // Try to import the planner module first. If this fails we're in Tier 3.
+    let mod;
+    try {
+        mod = await import('./planner/hierarchical/session-planner.js');
+    }
+    catch {
+        // Tier 3: stub fallback (current behavior).
+        return { planId: 'stub', steps: [] };
+    }
+    const planner = new mod.HierarchicalPlanner();
+    // Tier 1: real planner — needs both the env flag and agentOpts.
+    if (process.env.KBOT_PLANNER === 'hierarchical' && agentOpts) {
+        try {
+            const goal = await planner.createGoal({
+                title: state.name,
+                intent: state.mission,
+                acceptance: [taskInput],
+                tags: ['workspace-agent', state.id],
+            });
+            const result = await planner.planAndExecute(taskInput, {
+                sessionId: state.id,
+                agentOpts,
+                autoApprove: true,
+            });
+            const steps = result.action.steps;
+            const toolCalls = steps
+                .filter(s => typeof s.tool === 'string' && s.tool.length > 0)
+                .map(s => ({
+                tool: s.tool,
+                args: s.args,
+                result: s.result,
+            }));
+            return {
+                planId: goal.id,
+                steps,
+                toolCalls,
+            };
+        }
+        catch (err) {
+            // If tier-1 itself throws, don't crash the whole start() — degrade to
+            // Tier 2 so we still record the goal and a planner_note explaining why.
+            const msg = err instanceof Error ? err.message : String(err);
+            try {
+                const goal = await planner.createGoal({
+                    title: state.name,
+                    intent: state.mission,
+                    acceptance: [taskInput],
+                    tags: ['workspace-agent', state.id],
+                });
+                return {
+                    planId: goal.id,
+                    steps: [],
+                    notes: [
+                        `tier-1 planner failed (${msg}); recorded goal only`,
+                    ],
+                };
+            }
+            catch {
+                return { planId: 'stub', steps: [] };
+            }
+        }
+    }
+    // Tier 2: planner loadable but no agentOpts (or flag absent) — record a
+    // goal and surface a TODO so callers know to wire AgentOptions through.
+    try {
+        const goal = await planner.createGoal({
+            title: state.name,
+            intent: state.mission,
+            acceptance: [taskInput],
+            tags: ['workspace-agent', state.id],
+        });
+        return {
+            planId: goal.id,
+            steps: [],
+            notes: [
+                'real planAndExecute requires AgentOptions; configure caller to pass them.',
+            ],
+        };
+    }
+    catch {
+        // Tier 3: createGoal failed (e.g. read-only home dir) → stub.
+        return { planId: 'stub', steps: [] };
+    }
+};
+export class WorkspaceAgent {
+    root;
+    plannerStart;
+    constructor(opts = {}) {
+        this.root = opts.root ?? defaultRoot();
+        this.plannerStart = opts.plannerStart ?? defaultPlannerStart;
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    async create(opts) {
+        if (!opts.name || !opts.name.trim()) {
+            throw new WorkspaceAgentError('create: name is required');
+        }
+        if (!opts.mission || !opts.mission.trim()) {
+            throw new WorkspaceAgentError('create: mission is required');
+        }
+        const existing = await listAll(this.root);
+        if (existing.some(s => s.name === opts.name)) {
+            throw new WorkspaceAgentError(`create: an agent named "${opts.name}" already exists in this workspace`);
+        }
+        const now = new Date().toISOString();
+        const state = {
+            id: randomUUID(),
+            name: opts.name,
+            mission: opts.mission,
+            allowedTools: opts.allowedTools ?? [],
+            scopes: opts.scopes ?? [],
+            status: 'idle',
+            createdAt: now,
+            updatedAt: now,
+            history: [
+                { ts: now, event: 'created', data: { name: opts.name } },
+            ],
+        };
+        await writeState(this.root, state);
+        return { id: state.id, name: state.name };
+    }
+    async start(agentId, taskInput, agentOpts = null) {
+        const state = await this.requireState(agentId);
+        if (state.status === 'running') {
+            throw new WorkspaceAgentError(`start: agent ${agentId} is already running`);
+        }
+        if (state.status === 'completed') {
+            throw new WorkspaceAgentError(`start: agent ${agentId} is completed; create a new agent`);
+        }
+        state.status = 'running';
+        state.updatedAt = new Date().toISOString();
+        state.history.push({
+            ts: state.updatedAt,
+            event: 'started',
+            data: { taskInput },
+        });
+        await writeState(this.root, state);
+        let planResult;
+        try {
+            planResult = await this.plannerStart(taskInput, state, agentOpts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            state.status = 'failed';
+            state.updatedAt = new Date().toISOString();
+            state.history.push({
+                ts: state.updatedAt,
+                event: 'planner_error',
+                data: { message: msg },
+            });
+            await writeState(this.root, state);
+            throw new WorkspaceAgentError(`start: planner failed: ${msg}`);
+        }
+        state.currentPlanId = planResult.planId;
+        state.updatedAt = new Date().toISOString();
+        state.history.push({
+            ts: state.updatedAt,
+            event: 'plan_created',
+            data: { planId: planResult.planId, stepCount: planResult.steps.length },
+        });
+        await writeState(this.root, state);
+        // Surface any planner-emitted notes onto the agent's timeline.
+        if (planResult.notes && planResult.notes.length > 0) {
+            for (const note of planResult.notes) {
+                await this.appendEvent(agentId, 'planner_note', { message: note });
+            }
+        }
+        // Gate + record every tool call the planner produced. ScopeError from
+        // gate() must NOT escape start() — convert to a `tool_blocked` event and
+        // continue with the rest.
+        if (planResult.toolCalls && planResult.toolCalls.length > 0) {
+            for (const call of planResult.toolCalls) {
+                try {
+                    await this.gate(agentId, call.tool);
+                }
+                catch (err) {
+                    if (err instanceof ScopeError) {
+                        await this.appendEvent(agentId, 'tool_blocked', {
+                            tool: call.tool,
+                            reason: err.message,
+                        });
+                        continue;
+                    }
+                    throw err;
+                }
+                await this.recordToolCall(agentId, call.tool, call.args, call.result);
+            }
+        }
+        return {
+            id: state.id,
+            status: state.status,
+            planId: planResult.planId,
+            steps: planResult.steps,
+        };
+    }
+    async resume(agentId) {
+        const state = await this.requireState(agentId);
+        if (state.status !== 'paused' && state.status !== 'failed') {
+            throw new WorkspaceAgentError(`resume: agent ${agentId} has status "${state.status}"; resume only allowed from paused or failed`);
+        }
+        state.status = 'running';
+        state.updatedAt = new Date().toISOString();
+        state.history.push({ ts: state.updatedAt, event: 'resumed' });
+        await writeState(this.root, state);
+        return state;
+    }
+    async stop(agentId) {
+        const state = await this.requireState(agentId);
+        state.status = 'paused';
+        state.updatedAt = new Date().toISOString();
+        state.history.push({ ts: state.updatedAt, event: 'stopped' });
+        await writeState(this.root, state);
+        return state;
+    }
+    async status(agentId) {
+        return this.requireState(agentId);
+    }
+    async list() {
+        const all = await listAll(this.root);
+        return all.map(s => ({ id: s.id, name: s.name, status: s.status }));
+    }
+    /**
+     * Permission gate. Throws ScopeError if the tool isn't in allowedTools and
+     * appends a `tool_denied` event to history. On allow, appends `tool_allowed`.
+     */
+    async gate(agentId, toolName) {
+        const state = await this.requireState(agentId);
+        if (!state.allowedTools.includes(toolName)) {
+            state.history.push({
+                ts: new Date().toISOString(),
+                event: 'tool_denied',
+                data: { tool: toolName },
+            });
+            state.updatedAt = new Date().toISOString();
+            await writeState(this.root, state);
+            throw new ScopeError(toolName);
+        }
+        state.history.push({
+            ts: new Date().toISOString(),
+            event: 'tool_allowed',
+            data: { tool: toolName },
+        });
+        state.updatedAt = new Date().toISOString();
+        await writeState(this.root, state);
+    }
+    /**
+     * Append a tool-call record to the agent's history. Caller must call
+     * `gate()` first; this method does NOT enforce permissions.
+     */
+    async recordToolCall(agentId, toolName, args, result) {
+        const state = await this.requireState(agentId);
+        state.history.push({
+            ts: new Date().toISOString(),
+            event: 'tool_call',
+            data: { tool: toolName, args, result },
+        });
+        state.updatedAt = new Date().toISOString();
+        await writeState(this.root, state);
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    async appendEvent(agentId, event, data) {
+        const state = await this.requireState(agentId);
+        const ts = new Date().toISOString();
+        state.history.push({ ts, event, data });
+        state.updatedAt = ts;
+        await writeState(this.root, state);
+    }
+    async requireState(agentId) {
+        const state = await readState(this.root, agentId);
+        if (!state) {
+            throw new WorkspaceAgentError(`agent ${agentId} not found`);
+        }
+        return state;
+    }
+}
+//# sourceMappingURL=workspace-agents.js.map