@shuyhere/takotako 0.0.1

package/docs/skills.md

@@ -0,0 +1,246 @@
+# Skill Arms
+
+Skills are Tako's extensibility mechanism — pluggable capabilities loaded from the filesystem at runtime.
+
+## What is a Skill?
+
+A skill is a directory containing a `SKILL.md` file. The file has YAML frontmatter for metadata and a Markdown body with instructions that get injected into the agent's system prompt.
+
+```
+my-skill/
+├── SKILL.md          # Required: metadata + instructions
+├── tools/            # Optional: tool implementations (.js/.mjs)
+├── scripts/          # Optional: helper scripts
+├── references/       # Optional: reference docs loaded on-demand
+└── assets/           # Optional: templates, icons, etc.
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: my-skill
+description: What the skill does and when to use it
+version: 1.0.0
+author: Your Name
+triggers: keyword1, keyword2
+user-invocable: true
+disable-model-invocation: false
+requires: {"bins": ["node"], "env": ["API_KEY"], "os": ["linux", "darwin"]}
+---
+
+# My Skill
+
+Instructions for the agent on when and how to use this skill.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique skill identifier |
+| `description` | Yes | What the skill does — also used for trigger matching |
+| `version` | No | Semantic version (default: `0.1.0`) |
+| `author` | No | Author name |
+| `triggers` | No | When to activate (see below) |
+| `tools` | No | Tool names this skill provides |
+| `hooks` | No | Hook events this skill listens to |
+| `user-invocable` | No | Whether exposed as slash command (default: `true`) |
+| `disable-model-invocation` | No | Exclude from automatic prompt injection (default: `false`) |
+| `requires` | No | JSON object with platform requirements |
+
+### Trigger Types
+
+Triggers determine when a skill's instructions are injected into the system prompt.
+
+**Keyword triggers** (comma-separated):
+```yaml
+triggers: deploy, ship it, release
+```
+Matches if any keyword appears in the user's message (case-insensitive).
+
+**Pattern trigger** (regex):
+```yaml
+triggers: [{"type":"pattern","value":"\\b(deploy|ship)\\b"}]
+```
+
+**Always active:**
+```yaml
+triggers: always
+```
+
+**Manual only** (slash command only, never auto-injected):
+```yaml
+triggers: manual
+```
+
+**No triggers defined**: skill is always active (same as `always`).
+
+### Requirements
+
+Skills can declare platform requirements that are checked at load time:
+
+```yaml
+requires: {"bins": ["docker"], "env": ["DOCKER_HOST"], "os": ["linux"]}
+```
+
+- `bins`: Required binaries on PATH
+- `anyBins`: At least one must exist
+- `env`: Required environment variables
+- `os`: Required OS platforms (`linux`, `darwin`, `win32`)
+
+Skills that don't meet requirements are silently skipped.
+
+## Providing Tools
+
+Skills can provide additional tools by placing JavaScript modules in a `tools/` directory:
+
+```javascript
+// my-skill/tools/my-tool.js
+export default {
+  name: 'my_tool',
+  description: 'Does something useful',
+  parameters: {
+    type: 'object',
+    properties: {
+      input: { type: 'string', description: 'The input' }
+    },
+    required: ['input']
+  },
+  async execute(params, ctx) {
+    return { output: `Result: ${params.input}`, success: true };
+  }
+};
+```
+
+Tool modules can export:
+- A single tool as `default`
+- An array of tools as `default`
+- A named `tools` array
+
+Skill tools are registered with the tool registry when the skill loads. They are ungrouped, meaning they're always active regardless of the tool profile.
+
+## CLI Commands
+
+```bash
+# List all discovered skills
+tako skills list
+
+# Show details about a specific skill
+tako skills info find-skills
+
+# Install a skill from the ecosystem
+tako skills install vercel-labs/agent-skills@find-skills
+```
+
+## Hot Reload
+
+Tako watches skill directories for changes. When a `SKILL.md` or tool file is modified:
+
+1. All skills are re-discovered and re-loaded
+2. Tool registrations are updated
+3. Hook bindings are refreshed
+4. No restart required
+
+The reload is debounced (250ms) to handle rapid file changes.
+
+## Built-in Skills
+
+Tako ships with four built-in skills:
+
+### find-skills
+Discovers and installs skills from the ecosystem. Triggers when users ask about finding capabilities or extending the agent.
+
+### skill-creator
+Creates new skills from scratch with an iterative draft → test → review → improve workflow. Includes evaluation tooling for measuring skill performance.
+
+### security-audit
+Security scanning and analysis capabilities.
+
+### skill-security-audit
+Security audit for skill arms (from ClawHub). Validates skill safety before installation.
+
+## Creating a Skill
+
+1. Create a directory in `./skills/`:
+   ```bash
+   mkdir -p skills/my-skill
+   ```
+
+2. Write a `SKILL.md` with frontmatter and instructions:
+   ```markdown
+   ---
+   name: my-skill
+   description: Helps with X when the user asks about Y
+   version: 0.1.0
+   triggers: x, y, z
+   ---
+
+   # My Skill
+
+   When the user asks about X, follow these steps...
+   ```
+
+3. The skill loads automatically (hot reload) or on next `tako start`.
+
+4. Verify: `tako skills list`
+
+## Providing Extensions
+
+Skills can provide entire subsystem implementations by including extension subdirectories. The loader auto-detects these during skill loading.
+
+### Supported Extension Types
+
+- **channel/** — Messaging adapter (implements `Channel`)
+- **provider/** — LLM inference backend (implements `Provider`)
+- **memory/** — Persistence + recall backend (implements `MemoryStore`)
+- **network/** — Tunnel/exposure adapter (implements `NetworkAdapter`)
+- **sandbox/** — Code execution sandbox (implements `SandboxProvider`)
+- **auth/** — Authentication provider (implements `AuthProvider`)
+
+### Extension Module Convention
+
+Each extension subdirectory must contain an entry point (`index.ts`, `index.js`, `<type>.ts`, or `<type>.js`) that exports a factory function:
+
+```typescript
+// skills/my-provider/provider/index.ts
+import type { Provider } from 'tako/providers/provider.js';
+
+export function createProvider(config: Record<string, unknown>): Provider {
+  return {
+    id: 'my-provider',
+    async *chat(req) { /* ... */ yield { done: true }; },
+    models() { return []; },
+    supports(cap) { return false; },
+  };
+}
+```
+
+The loader tries these patterns in order:
+1. Named factory: `createChannel`, `createProvider`, `createMemory`, etc.
+2. Generic factory: `create(config)`
+3. Default export as constructor: `new mod.default(config)`
+
+### Extension Configuration
+
+Configure extensions in `tako.json` under `skillExtensions`:
+
+```json
+{
+  "skillExtensions": {
+    "ollama": {
+      "provider": { "baseUrl": "http://localhost:11434" }
+    },
+    "qdrant-memory": {
+      "memory": { "url": "http://localhost:6333", "collection": "tako" }
+    }
+  }
+}
+```
+
+### CLI
+
+```bash
+tako extensions list    # List all detected skill extensions
+tako extensions status  # Show runtime status (when running)
+```

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@shuyhere/takotako",
+  "version": "0.0.1",
+  "description": "Agent-as-CPU OS: minimal core + pluggable skill arms",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "tako": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "bun run tsc",
+    "dev": "bun run tsc --watch",
+    "start": "bun run src/index.ts",
+    "start:node": "node dist/index.js",
+    "doctor": "bun run src/index.ts doctor",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:node": "node --test --import tsx tests/*.test.ts",
+    "lint": "tsc --noEmit",
+    "check": "bun run build && bun run typecheck && bun test",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "ai",
+    "os",
+    "pluggable",
+    "skills",
+    "anthropic",
+    "discord",
+    "telegram",
+    "cli",
+    "tools",
+    "memory",
+    "streaming",
+    "websocket"
+  ],
+  "author": "shuyhere",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shuyhere/tako"
+  },
+  "homepage": "https://github.com/shuyhere/tako#readme",
+  "bugs": {
+    "url": "https://github.com/shuyhere/tako/issues"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "docs",
+    "tako.example.json",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@clack/prompts": "^1.1.0",
+    "@mariozechner/pi-coding-agent": "^0.56.1",
+    "discord.js": "^14.25.1",
+    "grammy": "^1.41.1",
+    "ink": "^6.8.0",
+    "ink-big-text": "^2.0.0",
+    "ink-gradient": "^4.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "open": "^11.0.0",
+    "openai": "^4.70.0",
+    "react": "^19.2.4",
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "playwright-core": "^1.58.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
+  }
+}

package/skills/acp-router/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: acp
+description: ACP harness router (acpx-backed) for Codex/Claude/Pi/OpenCode/Gemini/Kimi sessions
+version: 0.1.0
+author: Tako
+user-invocable: true
+command-dispatch: tool
+command-tool: acp_router
+command-arg-mode: raw
+triggers:
+  - type: keyword
+    value: acp
+  - type: keyword
+    value: codex
+  - type: keyword
+    value: claude code
+  - type: keyword
+    value: gemini cli
+---
+
+# ACP Router (acpx)
+
+Use `/acp` to route work into ACP harness agents.
+
+## Usage
+
+- `/acp <agent> <prompt>` — send prompt to a persistent ACP session (auto-created)
+- `/acp exec <agent> <prompt>` — one-shot (no persistent session)
+- `/acp list` — list known ACP session bindings in Tako
+- `/acp reset <agent>` — close and forget the bound session for this chat session
+- `/acp help` — show help
+
+## Agents
+
+Supported aliases: `pi`, `claude`, `codex`, `opencode`, `gemini`, `kimi`.
+
+## Notes
+
+- Prefers plugin-local `extensions/acpx/node_modules/.bin/acpx` when available.
+- Falls back to `acpx` from PATH.
+- Persistent session names are deterministic per Tako chat session + agent.

package/skills/acp-router/tools/acp-router.mjs

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const STORE_DIR = join(homedir(), '.tako', 'acp');
+const STORE_FILE = join(STORE_DIR, 'router-sessions.json');
+
+const AGENT_ALIASES = new Set(['pi', 'claude', 'codex', 'opencode', 'gemini', 'kimi']);
+
+function detectAcpx() {
+  const envCmd = process.env.ACPX_CMD;
+  if (envCmd) return envCmd;
+
+  const local = join(process.cwd(), 'extensions', 'acpx', 'node_modules', '.bin', 'acpx');
+  if (existsSync(local)) return local;
+
+  return 'acpx';
+}
+
+async function loadStore() {
+  try {
+    const raw = await readFile(STORE_FILE, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveStore(store) {
+  await mkdir(STORE_DIR, { recursive: true });
+  await writeFile(STORE_FILE, JSON.stringify(store, null, 2), 'utf-8');
+}
+
+function shlex(input) {
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let esc = false;
+
+  for (const ch of input) {
+    if (esc) {
+      current += ch;
+      esc = false;
+      continue;
+    }
+    if (ch === '\\') {
+      esc = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function run(cmd, args, cwd, timeoutMs = 20 * 60 * 1000) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let out = '';
+    let err = '';
+
+    child.stdout?.on('data', (d) => { out += String(d); });
+    child.stderr?.on('data', (d) => { err += String(d); });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      resolve({ ok: false, code: -1, stdout: out, stderr: `${err}\nTimed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({ ok: false, code: -1, stdout: out, stderr: `${err}\n${e.message}` });
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code: code ?? -1, stdout: out, stderr: err });
+    });
+  });
+}
+
+function sessionKey(ctx, agent) {
+  return `${ctx.sessionId}:${agent}`;
+}
+
+function defaultSessionName(ctx, agent) {
+  const sid = String(ctx.sessionId || 'session').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 24);
+  return `tako-${agent}-${sid}`;
+}
+
+function helpText() {
+  return [
+    'ACP Router',
+    '',
+    'Usage:',
+    '  /acp <agent> <prompt>         Send prompt to persistent ACP session',
+    '  /acp exec <agent> <prompt>    One-shot ACP execution',
+    '  /acp list                      List ACP bindings for this Tako instance',
+    '  /acp reset <agent>             Close + forget bound ACP session',
+    '  /acp help                      Show this help',
+    '',
+    'Agents: pi, claude, codex, opencode, gemini, kimi',
+  ].join('\n');
+}
+
+const acpRouterTool = {
+  name: 'acp_router',
+  description: 'Route ACP harness commands to acpx (persistent or one-shot).',
+  parameters: {
+    type: 'object',
+    properties: {
+      input: { type: 'string', description: 'Raw /acp command args' },
+    },
+    required: ['input'],
+  },
+  async execute(params, ctx) {
+    const input = String(params?.input || '').trim();
+    if (!input || input === 'help') {
+      return { success: true, output: helpText() };
+    }
+
+    const acpx = detectAcpx();
+    const cwd = ctx.workDir || process.cwd();
+    const store = await loadStore();
+    const tokens = shlex(input);
+
+    const versionCheck = await run(acpx, ['--version'], cwd, 15000);
+    if (!versionCheck.ok) {
+      return {
+        success: false,
+        error: [
+          `acpx is not available (${acpx}).`,
+          'Install it with: npm i -g acpx',
+          'Or set ACPX_CMD to a valid binary path.',
+        ].join(' '),
+      };
+    }
+
+    const first = (tokens[0] || '').toLowerCase();
+
+    if (first === 'list') {
+      const entries = Object.entries(store);
+      if (entries.length === 0) return { success: true, output: 'No ACP session bindings yet.' };
+      const lines = entries.map(([k, v]) => `${k} -> ${v.agent}:${v.sessionName}`);
+      return { success: true, output: `ACP bindings:\n${lines.join('\n')}` };
+    }
+
+    if (first === 'reset') {
+      const agent = (tokens[1] || '').toLowerCase();
+      if (!AGENT_ALIASES.has(agent)) {
+        return { success: false, error: `Invalid agent "${agent}". Use: pi|claude|codex|opencode|gemini|kimi` };
+      }
+      const key = sessionKey(ctx, agent);
+      const bound = store[key];
+      if (!bound?.sessionName) {
+        return { success: true, output: `No bound session for ${agent} in this chat session.` };
+      }
+      const closeRes = await run(acpx, [agent, 'sessions', 'close', bound.sessionName], cwd, 120000);
+      delete store[key];
+      await saveStore(store);
+      if (closeRes.ok) return { success: true, output: `Closed ACP session ${bound.sessionName} (${agent}).` };
+      return { success: true, output: `Unbound ${bound.sessionName} (${agent}).\n(close returned non-zero: ${closeRes.stderr || closeRes.stdout || 'unknown'})` };
+    }
+
+    if (first === 'exec') {
+      const agent = (tokens[1] || '').toLowerCase();
+      const prompt = tokens.slice(2).join(' ').trim();
+      if (!AGENT_ALIASES.has(agent)) {
+        return { success: false, error: `Invalid agent "${agent}". Use: pi|claude|codex|opencode|gemini|kimi` };
+      }
+      if (!prompt) return { success: false, error: 'Missing prompt. Usage: /acp exec <agent> <prompt>' };
+
+      const res = await run(acpx, [agent, 'exec', '--cwd', cwd, '--format', 'quiet', prompt], cwd);
+      if (!res.ok) {
+        return { success: false, error: `acpx exec failed: ${res.stderr || res.stdout || 'unknown error'}` };
+      }
+      return { success: true, output: res.stdout || '(no output)' };
+    }
+
+    // Default mode: /acp <agent> <prompt>
+    const agent = first;
+    const prompt = tokens.slice(1).join(' ').trim();
+
+    if (!AGENT_ALIASES.has(agent)) {
+      return { success: false, error: `Invalid subcommand/agent "${agent}". Try /acp help` };
+    }
+    if (!prompt) {
+      return { success: false, error: 'Missing prompt. Usage: /acp <agent> <prompt>' };
+    }
+
+    const key = sessionKey(ctx, agent);
+    const existing = store[key];
+    const sessionName = existing?.sessionName || defaultSessionName(ctx, agent);
+
+    // Ensure session exists (best-effort create)
+    await run(acpx, [agent, 'sessions', 'new', '--name', sessionName], cwd, 120000);
+
+    const sendRes = await run(acpx, [agent, '-s', sessionName, '--cwd', cwd, '--format', 'quiet', prompt], cwd);
+    if (!sendRes.ok) {
+      return { success: false, error: `acpx session send failed: ${sendRes.stderr || sendRes.stdout || 'unknown error'}` };
+    }
+
+    store[key] = { agent, sessionName, updatedAt: Date.now() };
+    await saveStore(store);
+
+    return {
+      success: true,
+      output: sendRes.stdout || '(no output)',
+      data: { agent, sessionName },
+    };
+  },
+};
+
+export const tools = [acpRouterTool];
+export default tools;