@shuyhere/takotako 0.0.1

package/dist/agents/roles.js

@@ -0,0 +1,174 @@
+/**
+ * Agent permission roles for Tako.
+ *
+ * The root agent (created at first onboarding) has admin permissions.
+ * Sub-agents are created with a specific role that limits what they can do.
+ *
+ * Predefined roles:
+ *   admin      — full control: create/delete agents, manage roles, all tools, config
+ *   operator   — manage agents and run all tools, but can't change roles or config
+ *   editor     — read/write files, safe commands, no exec or config changes
+ *   standard   — use all tools, can spawn sub-agents from its allowlist
+ *   viewer     — read-only access, search and memory tools
+ *   restricted — limited tools (no exec, no file write outside workspace)
+ *   readonly   — can only read files and respond, no side effects
+ *
+ * Per-user role overrides: map platform user IDs to specific roles.
+ * Config: agents.list[].roles: { default: RoleName; users?: Record<string, RoleName> }
+ *
+ * Custom roles can be created by the root agent at runtime.
+ */
+/** Predefined roles. */
+export const PREDEFINED_ROLES = {
+    admin: {
+        name: 'admin',
+        description: 'Full control — create agents, manage roles, all tools, config',
+        allowTools: [],
+        denyTools: [],
+        canCreateAgents: true,
+        canDeleteAgents: true,
+        canManageRoles: true,
+        canEditConfig: true,
+        canExec: true,
+        canWriteGlobal: true,
+        canBindChannels: true,
+    },
+    operator: {
+        name: 'operator',
+        description: 'Manage agents and run all tools, but no role/config changes',
+        allowTools: [],
+        denyTools: [],
+        canCreateAgents: true,
+        canDeleteAgents: false,
+        canManageRoles: false,
+        canEditConfig: false,
+        canExec: true,
+        canWriteGlobal: true,
+        canBindChannels: true,
+    },
+    editor: {
+        name: 'editor',
+        description: 'Read/write files and safe commands — no exec, no config changes',
+        allowTools: ['read', 'write', 'edit', 'list_directory', 'memory_search', 'memory_write',
+            'web_search', 'web_fetch', 'apply_patch'],
+        denyTools: ['exec', 'shell', 'exec_command', 'cron_add', 'cron_remove',
+            'agents_add', 'agents_remove'],
+        canCreateAgents: false,
+        canDeleteAgents: false,
+        canManageRoles: false,
+        canEditConfig: false,
+        canExec: false,
+        canWriteGlobal: false,
+        canBindChannels: false,
+    },
+    standard: {
+        name: 'standard',
+        description: 'All tools, can spawn sub-agents from allowlist',
+        allowTools: [],
+        denyTools: [],
+        canCreateAgents: false,
+        canDeleteAgents: false,
+        canManageRoles: false,
+        canEditConfig: false,
+        canExec: true,
+        canWriteGlobal: false,
+        canBindChannels: false,
+    },
+    viewer: {
+        name: 'viewer',
+        description: 'Read-only with search — can read files, search, and use memory',
+        allowTools: ['read', 'list_directory', 'memory_search', 'web_search', 'web_fetch'],
+        denyTools: ['exec', 'shell', 'write', 'edit', 'exec_command', 'apply_patch',
+            'cron_add', 'cron_remove', 'agents_add', 'agents_remove', 'memory_write'],
+        canCreateAgents: false,
+        canDeleteAgents: false,
+        canManageRoles: false,
+        canEditConfig: false,
+        canExec: false,
+        canWriteGlobal: false,
+        canBindChannels: false,
+    },
+    restricted: {
+        name: 'restricted',
+        description: 'Limited tools — no exec, no writes outside workspace',
+        allowTools: [],
+        denyTools: ['exec', 'shell', 'exec_command'],
+        canCreateAgents: false,
+        canDeleteAgents: false,
+        canManageRoles: false,
+        canEditConfig: false,
+        canExec: false,
+        canWriteGlobal: false,
+        canBindChannels: false,
+    },
+    readonly: {
+        name: 'readonly',
+        description: 'Read-only — can read files and respond, no side effects',
+        allowTools: ['read', 'list_directory', 'memory_search', 'web_search', 'web_fetch'],
+        denyTools: ['exec', 'shell', 'write', 'edit', 'exec_command', 'cron_add', 'cron_remove', 'agents_add', 'agents_remove'],
+        canCreateAgents: false,
+        canDeleteAgents: false,
+        canManageRoles: false,
+        canEditConfig: false,
+        canExec: false,
+        canWriteGlobal: false,
+        canBindChannels: false,
+    },
+};
+/** Check if a tool call is allowed for a given role. */
+export function isToolAllowed(role, toolName) {
+    // Deny list takes priority
+    if (role.denyTools.length > 0 && role.denyTools.includes(toolName))
+        return false;
+    // If allow list is specified (non-empty), tool must be in it
+    if (role.allowTools.length > 0)
+        return role.allowTools.includes(toolName);
+    // Empty allow = all allowed
+    return true;
+}
+/** Get a role by name (predefined or custom). */
+export function getRole(name, customRoles) {
+    return PREDEFINED_ROLES[name] ?? customRoles?.[name] ?? null;
+}
+/** List all available role names. */
+export function listRoles(customRoles) {
+    return [...Object.keys(PREDEFINED_ROLES), ...Object.keys(customRoles ?? {})];
+}
+/**
+ * Resolve the effective role for a user interacting with an agent.
+ *
+ * Resolution order:
+ * 1. Per-user override in AgentRoleConfig.users
+ * 2. Agent's default role (AgentRoleConfig.default)
+ * 3. Fallback to 'standard'
+ */
+export function resolveUserRole(roleConfig, userId, customRoles) {
+    if (!roleConfig) {
+        return PREDEFINED_ROLES['standard'];
+    }
+    // Check per-user override
+    if (userId && roleConfig.users?.[userId]) {
+        const role = getRole(roleConfig.users[userId], customRoles);
+        if (role)
+            return role;
+    }
+    // Use agent default
+    const role = getRole(roleConfig.default, customRoles);
+    return role ?? PREDEFINED_ROLES['standard'];
+}
+/**
+ * Check if a tool call is allowed for a specific user on a specific agent.
+ * Convenience function that resolves the role and checks in one call.
+ */
+export function checkToolPermission(toolName, roleConfig, userId, customRoles) {
+    const role = resolveUserRole(roleConfig, userId, customRoles);
+    if (!isToolAllowed(role, toolName)) {
+        return {
+            allowed: false,
+            role,
+            reason: `Role '${role.name}' does not allow tool '${toolName}'`,
+        };
+    }
+    return { allowed: true, role };
+}
+//# sourceMappingURL=roles.js.map

package/dist/agents/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/agents/roles.ts"],"names":[],"mappings":"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"}

package/dist/agents/subagent.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Sub-agent orchestration — spawn, track, steer, and kill sub-agents.
+ *
+ * Supports two modes:
+ * - "run" (one-shot): Execute a task, return result, clean up
+ * - "session" (persistent): Persistent agent that can receive follow-up messages
+ *
+ * reference runtime-aligned features:
+ * - Configurable timeout per spawn (default 5min for run, none for session)
+ * - Completion announcements: push results to parent session
+ * - Automatic cleanup: remove completed run-mode sessions after result retrieval
+ * - Session key routing: agent:<id>:<mode>:<uuid> format
+ * - Thread-bound persistence: session mode runs persist across restarts
+ */
+import type { AgentLoop } from '../core/agent-loop.js';
+import type { SessionManager } from '../gateway/session.js';
+import type { AgentDescriptor } from './config.js';
+/** Sub-agent run mode. */
+export type SubAgentMode = 'run' | 'session';
+/** Sub-agent status. */
+export type SubAgentStatus = 'running' | 'completed' | 'failed' | 'killed' | 'timeout';
+/** Options for spawning a sub-agent. */
+export interface SpawnOptions {
+    /** Task description / initial message. */
+    task: string;
+    /** Agent ID to use (defaults to parent's agent). */
+    agentId?: string;
+    /** Run mode: one-shot or persistent. */
+    mode: SubAgentMode;
+    /** Human-readable label for tracking. */
+    label?: string;
+    /** Model override. */
+    model?: string;
+    /** Timeout in milliseconds (default: 300_000 for run, 0 for session). */
+    timeoutMs?: number;
+    /** Whether to announce completion to the parent session. */
+    announceCompletion?: boolean;
+}
+/** A tracked sub-agent run. */
+export interface SubAgentRun {
+    /** Unique run ID. */
+    id: string;
+    /** Parent session ID that spawned this run. */
+    parentSessionId: string;
+    /** Agent ID being used. */
+    agentId: string;
+    /** The session this sub-agent is using. */
+    sessionId: string;
+    /** Session key for routing. */
+    sessionKey: string;
+    /** Run mode. */
+    mode: SubAgentMode;
+    /** Human-readable label. */
+    label: string;
+    /** Current status. */
+    status: SubAgentStatus;
+    /** Task that was given. */
+    task: string;
+    /** Result text (populated on completion). */
+    result?: string;
+    /** Error message (populated on failure). */
+    error?: string;
+    /** When the run started. */
+    startedAt: Date;
+    /** When the run completed/failed. */
+    completedAt?: Date;
+    /** Timeout in milliseconds. */
+    timeoutMs: number;
+    /** Whether to announce completion to parent. */
+    announceCompletion: boolean;
+}
+/** Completion event emitted when a sub-agent finishes. */
+export interface SubAgentCompletionEvent {
+    runId: string;
+    parentSessionId: string;
+    status: SubAgentStatus;
+    result?: string;
+    error?: string;
+}
+export type CompletionHandler = (event: SubAgentCompletionEvent) => void;
+export declare class SubAgentOrchestrator {
+    private runs;
+    private sessions;
+    private agentLoop;
+    private completionHandlers;
+    private timeoutTimers;
+    constructor(sessions: SessionManager, agentLoop: AgentLoop);
+    /** Load runs from ~/.tako/subagents/runs.json on startup. */
+    private loadPersistedRuns;
+    /** Persist all runs to ~/.tako/subagents/runs.json. */
+    private saveRuns;
+    /** Register a handler for sub-agent completion events. */
+    onCompletion(handler: CompletionHandler): void;
+    /**
+     * Spawn a sub-agent.
+     * In "run" mode, executes the task and returns the result.
+     * In "session" mode, starts the session and returns immediately.
+     */
+    spawn(parentSessionId: string, opts: SpawnOptions, _agent?: AgentDescriptor): Promise<SubAgentRun>;
+    /** Execute a sub-agent run. */
+    private executeRun;
+    /** Send a follow-up message to a persistent sub-agent session. */
+    sendMessage(runId: string, message: string): Promise<string>;
+    /** List all sub-agent runs, optionally filtered by parent session. */
+    listRuns(parentSessionId?: string): SubAgentRun[];
+    /** Get a specific run. */
+    getRun(runId: string): SubAgentRun | undefined;
+    /** Kill a running sub-agent. */
+    kill(runId: string): boolean;
+    /** Steer a sub-agent by sending it additional instructions. */
+    steer(runId: string, message: string): Promise<string>;
+    /**
+     * Clean up completed run-mode sessions.
+     * Removes run records and their sessions after results have been retrieved.
+     */
+    cleanup(): number;
+    /** Restore thread-bound sessions from persisted session data on restart. */
+    restorePersistedSessions(): number;
+    private clearTimeout;
+    private emitCompletion;
+    /** Push completion announcement to the parent session. */
+    private announceToParent;
+}
+//# sourceMappingURL=subagent.d.ts.map

package/dist/agents/subagent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.d.ts","sourceRoot":"","sources":["../../src/agents/subagent.ts"],"names":[],"mappings":"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"}

package/dist/agents/subagent.js

@@ -0,0 +1,352 @@
+/**
+ * Sub-agent orchestration — spawn, track, steer, and kill sub-agents.
+ *
+ * Supports two modes:
+ * - "run" (one-shot): Execute a task, return result, clean up
+ * - "session" (persistent): Persistent agent that can receive follow-up messages
+ *
+ * reference runtime-aligned features:
+ * - Configurable timeout per spawn (default 5min for run, none for session)
+ * - Completion announcements: push results to parent session
+ * - Automatic cleanup: remove completed run-mode sessions after result retrieval
+ * - Session key routing: agent:<id>:<mode>:<uuid> format
+ * - Thread-bound persistence: session mode runs persist across restarts
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+/** Default timeout: 5 minutes for run mode, 0 (no timeout) for session mode. */
+const DEFAULT_RUN_TIMEOUT_MS = 300_000;
+function getRunsPath() {
+    return join(homedir(), '.tako', 'subagents', 'runs.json');
+}
+export class SubAgentOrchestrator {
+    runs = new Map();
+    sessions;
+    agentLoop;
+    completionHandlers = [];
+    timeoutTimers = new Map();
+    constructor(sessions, agentLoop) {
+        this.sessions = sessions;
+        this.agentLoop = agentLoop;
+        // Load persisted runs on construction
+        this.loadPersistedRuns().catch(() => { });
+    }
+    /** Load runs from ~/.tako/subagents/runs.json on startup. */
+    async loadPersistedRuns() {
+        const filePath = getRunsPath();
+        if (!existsSync(filePath))
+            return;
+        try {
+            const raw = await readFile(filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            for (const sr of data.runs) {
+                if (this.runs.has(sr.id))
+                    continue;
+                const run = {
+                    id: sr.id,
+                    parentSessionId: sr.parentSessionId,
+                    agentId: sr.agentId,
+                    sessionId: sr.sessionId,
+                    sessionKey: sr.sessionKey,
+                    mode: sr.mode,
+                    label: sr.label,
+                    status: sr.status,
+                    task: sr.task,
+                    startedAt: new Date(sr.startedAt),
+                    completedAt: sr.completedAt ? new Date(sr.completedAt) : undefined,
+                    timeoutMs: 0,
+                    announceCompletion: false,
+                };
+                this.runs.set(sr.id, run);
+            }
+            console.log(`[subagent] Loaded ${data.runs.length} persisted runs`);
+        }
+        catch {
+            // Corrupted file — start fresh
+        }
+    }
+    /** Persist all runs to ~/.tako/subagents/runs.json. */
+    async saveRuns() {
+        const filePath = getRunsPath();
+        const dir = join(filePath, '..');
+        await mkdir(dir, { recursive: true });
+        const serialized = [];
+        for (const run of this.runs.values()) {
+            serialized.push({
+                id: run.id,
+                parentSessionId: run.parentSessionId,
+                agentId: run.agentId,
+                sessionId: run.sessionId,
+                sessionKey: run.sessionKey,
+                mode: run.mode,
+                label: run.label,
+                status: run.status,
+                task: run.task,
+                startedAt: run.startedAt.toISOString(),
+                completedAt: run.completedAt?.toISOString(),
+            });
+        }
+        const data = { version: 1, runs: serialized };
+        await writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    }
+    /** Register a handler for sub-agent completion events. */
+    onCompletion(handler) {
+        this.completionHandlers.push(handler);
+    }
+    /**
+     * Spawn a sub-agent.
+     * In "run" mode, executes the task and returns the result.
+     * In "session" mode, starts the session and returns immediately.
+     */
+    async spawn(parentSessionId, opts, _agent) {
+        const runId = crypto.randomUUID();
+        const agentId = opts.agentId ?? 'main';
+        // Build session key: agent:<id>:<mode>:<uuid>
+        const sessionKey = `agent:${agentId}:${opts.mode}:${runId}`;
+        // Determine timeout
+        const timeoutMs = opts.timeoutMs ??
+            (opts.mode === 'run' ? DEFAULT_RUN_TIMEOUT_MS : 0);
+        // Create a new session for the sub-agent with proper key routing
+        const session = this.sessions.getOrCreate(sessionKey, {
+            name: `subagent:${opts.label ?? agentId}:${runId.slice(0, 8)}`,
+            metadata: {
+                parentSessionId,
+                agentId,
+                mode: opts.mode,
+                label: opts.label,
+                isSubAgent: true,
+                sessionKey,
+                // Thread-bound: session mode persists across restarts
+                persistent: opts.mode === 'session',
+            },
+        });
+        const run = {
+            id: runId,
+            parentSessionId,
+            agentId,
+            sessionId: session.id,
+            sessionKey,
+            mode: opts.mode,
+            label: opts.label ?? `${agentId}:${runId.slice(0, 8)}`,
+            status: 'running',
+            task: opts.task,
+            startedAt: new Date(),
+            timeoutMs,
+            announceCompletion: opts.announceCompletion ?? true,
+        };
+        this.runs.set(runId, run);
+        this.saveRuns().catch(() => { });
+        // Set up timeout if configured
+        if (timeoutMs > 0) {
+            const timer = setTimeout(() => {
+                if (run.status === 'running') {
+                    run.status = 'timeout';
+                    run.error = `Timed out after ${timeoutMs}ms`;
+                    run.completedAt = new Date();
+                    this.timeoutTimers.delete(runId);
+                    this.emitCompletion(run);
+                }
+            }, timeoutMs);
+            this.timeoutTimers.set(runId, timer);
+        }
+        // Execute the run
+        this.executeRun(run, session).catch((err) => {
+            run.status = 'failed';
+            run.error = err instanceof Error ? err.message : String(err);
+            run.completedAt = new Date();
+            this.clearTimeout(runId);
+            this.emitCompletion(run);
+        });
+        return run;
+    }
+    /** Execute a sub-agent run. */
+    async executeRun(run, session) {
+        let result = '';
+        try {
+            for await (const chunk of this.agentLoop.run(session, run.task)) {
+                // Check if we've been killed or timed out while running
+                if (run.status === 'killed' || run.status === 'timeout')
+                    return;
+                result += chunk;
+            }
+            // Don't overwrite if already killed/timed out
+            if (run.status !== 'running')
+                return;
+            run.result = result;
+            run.status = 'completed';
+            run.completedAt = new Date();
+        }
+        catch (err) {
+            if (run.status !== 'running')
+                return;
+            run.status = 'failed';
+            run.error = err instanceof Error ? err.message : String(err);
+            run.completedAt = new Date();
+        }
+        this.clearTimeout(run.id);
+        // Automatic cleanup for completed run-mode sessions
+        if (run.mode === 'run') {
+            session.metadata.completed = true;
+        }
+        this.emitCompletion(run);
+    }
+    /** Send a follow-up message to a persistent sub-agent session. */
+    async sendMessage(runId, message) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error(`Sub-agent run not found: ${runId}`);
+        if (run.mode !== 'session')
+            throw new Error(`Cannot send messages to one-shot runs`);
+        if (run.status !== 'completed' && run.status !== 'running') {
+            throw new Error(`Sub-agent is ${run.status}, cannot send message`);
+        }
+        const session = this.sessions.get(run.sessionId);
+        if (!session)
+            throw new Error(`Session not found: ${run.sessionId}`);
+        run.status = 'running';
+        let result = '';
+        for await (const chunk of this.agentLoop.run(session, message)) {
+            result += chunk;
+        }
+        run.status = 'completed';
+        run.result = result;
+        return result;
+    }
+    /** List all sub-agent runs, optionally filtered by parent session. */
+    listRuns(parentSessionId) {
+        const all = Array.from(this.runs.values());
+        if (parentSessionId) {
+            return all.filter((r) => r.parentSessionId === parentSessionId);
+        }
+        return all;
+    }
+    /** Get a specific run. */
+    getRun(runId) {
+        return this.runs.get(runId);
+    }
+    /** Kill a running sub-agent. */
+    kill(runId) {
+        const run = this.runs.get(runId);
+        if (!run)
+            return false;
+        if (run.status !== 'running')
+            return false;
+        run.status = 'killed';
+        run.completedAt = new Date();
+        this.clearTimeout(runId);
+        this.emitCompletion(run);
+        return true;
+    }
+    /** Steer a sub-agent by sending it additional instructions. */
+    async steer(runId, message) {
+        return this.sendMessage(runId, message);
+    }
+    /**
+     * Clean up completed run-mode sessions.
+     * Removes run records and their sessions after results have been retrieved.
+     */
+    cleanup() {
+        let cleaned = 0;
+        for (const [runId, run] of this.runs) {
+            if (run.mode === 'run' &&
+                (run.status === 'completed' || run.status === 'failed' || run.status === 'timeout')) {
+                // Delete the session
+                this.sessions.delete(run.sessionId);
+                this.runs.delete(runId);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            console.log(`[subagent] Cleaned up ${cleaned} completed run-mode sessions`);
+        }
+        return cleaned;
+    }
+    /** Restore thread-bound sessions from persisted session data on restart. */
+    restorePersistedSessions() {
+        let restored = 0;
+        for (const session of this.sessions.list()) {
+            if (session.metadata.isSubAgent &&
+                session.metadata.persistent &&
+                session.metadata.sessionKey &&
+                !session.metadata.completed) {
+                const key = session.metadata.sessionKey;
+                // Parse the session key: agent:<id>:<mode>:<uuid>
+                const parts = key.split(':');
+                if (parts.length >= 4) {
+                    const runId = parts[3];
+                    if (!this.runs.has(runId)) {
+                        const run = {
+                            id: runId,
+                            parentSessionId: session.metadata.parentSessionId ?? '',
+                            agentId: parts[1],
+                            sessionId: session.id,
+                            sessionKey: key,
+                            mode: parts[2],
+                            label: session.metadata.label ?? session.name,
+                            status: 'completed',
+                            task: '',
+                            startedAt: session.createdAt,
+                            completedAt: session.lastActiveAt,
+                            timeoutMs: 0,
+                            announceCompletion: false,
+                        };
+                        this.runs.set(runId, run);
+                        restored++;
+                    }
+                }
+            }
+        }
+        if (restored > 0) {
+            console.log(`[subagent] Restored ${restored} persisted thread-bound sessions`);
+        }
+        return restored;
+    }
+    clearTimeout(runId) {
+        const timer = this.timeoutTimers.get(runId);
+        if (timer) {
+            clearTimeout(timer);
+            this.timeoutTimers.delete(runId);
+        }
+    }
+    emitCompletion(run) {
+        this.saveRuns().catch(() => { });
+        const event = {
+            runId: run.id,
+            parentSessionId: run.parentSessionId,
+            status: run.status,
+            result: run.result,
+            error: run.error,
+        };
+        // Announce completion to parent session if configured
+        if (run.announceCompletion && run.parentSessionId) {
+            this.announceToParent(run);
+        }
+        for (const handler of this.completionHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Don't let handler errors crash the orchestrator
+            }
+        }
+    }
+    /** Push completion announcement to the parent session. */
+    announceToParent(run) {
+        const parentSession = this.sessions.get(run.parentSessionId);
+        if (!parentSession)
+            return;
+        const statusEmoji = run.status === 'completed' ? '✓' : run.status === 'timeout' ? '⏱' : '✗';
+        const summary = run.status === 'completed'
+            ? (run.result ?? '').slice(0, 500)
+            : run.error ?? 'Unknown error';
+        const announcement = `[sub-agent ${statusEmoji}] ${run.label} (${run.status}): ${summary}`;
+        parentSession.messages.push({
+            role: 'system',
+            content: announcement,
+        });
+        parentSession.lastActiveAt = new Date();
+    }
+}
+//# sourceMappingURL=subagent.js.map