@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/ai-ml/skills/code-sandbox.md

@@ -1,187 +1,187 @@
----
-name: "code-sandbox"
-pack: "@rune/ai-ml"
-description: "Secure code execution for AI agents — sandboxed environments for running LLM-generated code safely with container isolation, resource limits, and timeout enforcement."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# code-sandbox
-
-Secure code execution for AI agents — sandboxed environments for running LLM-generated code safely. Covers container isolation, resource limits, timeout enforcement, file system boundaries, and output capture for code interpreter, CI/CD, and interactive development use cases.
-
-#### Workflow
-
-**Step 1 — Assess execution requirements**
-Determine what kind of code the agent needs to run:
-
-| Use Case | Isolation Level | Runtime |
-|---|---|---|
-| Code interpreter (data analysis, math) | High — untrusted code | Python + pandas/numpy |
-| Build/test pipeline | Medium — project code | Node.js / Python with project deps |
-| Interactive preview (web app) | Medium — expose HTTP port | Node.js + browser preview |
-| Shell commands (file ops, git) | Low — trusted context | System shell with path restrictions |
-
-**Step 2 — Configure sandbox environment**
-Emit sandbox configuration based on use case:
-
-```typescript
-// Sandbox factory — select isolation level by use case
-interface SandboxConfig {
-  language: 'python' | 'javascript' | 'typescript';
-  timeout: number;       // max execution time in ms
-  memoryLimit: number;   // max memory in MB
-  networkAccess: boolean;
-  fileSystemRoot: string;  // restricted working directory
-  allowedModules: string[];
-}
-
-const SANDBOX_PRESETS: Record<string, SandboxConfig> = {
-  'code-interpreter': {
-    language: 'python',
-    timeout: 30_000,
-    memoryLimit: 256,
-    networkAccess: false,
-    fileSystemRoot: '/workspace',
-    allowedModules: ['pandas', 'numpy', 'matplotlib', 'scipy', 'json', 'csv', 'math'],
-  },
-  'build-test': {
-    language: 'typescript',
-    timeout: 120_000,
-    memoryLimit: 512,
-    networkAccess: true,  // needs npm registry
-    fileSystemRoot: '/project',
-    allowedModules: ['*'],  // project dependencies
-  },
-  'preview': {
-    language: 'javascript',
-    timeout: 300_000,
-    memoryLimit: 256,
-    networkAccess: true,
-    fileSystemRoot: '/app',
-    allowedModules: ['*'],
-  },
-};
-```
-
-**Step 3 — Implement execution with resource limits**
-Emit code execution wrapper with safety boundaries:
-
-```typescript
-// Docker-based sandbox execution
-import { spawn } from 'child_process';
-
-interface ExecutionResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  durationMs: number;
-  timedOut: boolean;
-}
-
-async function executeInSandbox(
-  code: string,
-  config: SandboxConfig
-): Promise<ExecutionResult> {
-  const start = Date.now();
-
-  // Write code to temp file in sandbox root
-  const codePath = `${config.fileSystemRoot}/run.${config.language === 'python' ? 'py' : 'ts'}`;
-  await writeFile(codePath, code);
-
-  const proc = spawn('docker', [
-    'run', '--rm',
-    '--memory', `${config.memoryLimit}m`,
-    '--cpus', '1',
-    '--network', config.networkAccess ? 'bridge' : 'none',
-    '--read-only',
-    '--tmpfs', '/tmp:size=64m',
-    '-v', `${config.fileSystemRoot}:/workspace:ro`,
-    '-w', '/workspace',
-    `sandbox-${config.language}:latest`,
-    config.language === 'python' ? 'python' : 'npx tsx',
-    `/workspace/run.${config.language === 'python' ? 'py' : 'ts'}`,
-  ]);
-
-  let stdout = '';
-  let stderr = '';
-  let timedOut = false;
-
-  proc.stdout.on('data', (d) => { stdout += d.toString(); });
-  proc.stderr.on('data', (d) => { stderr += d.toString(); });
-
-  const timeout = setTimeout(() => {
-    timedOut = true;
-    proc.kill('SIGKILL');
-  }, config.timeout);
-
-  const exitCode = await new Promise<number>((resolve) => {
-    proc.on('close', (code) => {
-      clearTimeout(timeout);
-      resolve(code ?? 1);
-    });
-  });
-
-  return { stdout, stderr, exitCode, durationMs: Date.now() - start, timedOut };
-}
-```
-
-**Step 4 — Code interpreter mode (stateful sessions)**
-For multi-turn code execution where variables persist between runs:
-
-```typescript
-// Stateful code interpreter — variables persist across executions
-interface CodeSession {
-  id: string;
-  language: 'python' | 'javascript';
-  history: { code: string; result: ExecutionResult }[];
-}
-
-async function runInSession(
-  session: CodeSession,
-  code: string
-): Promise<ExecutionResult> {
-  // Python: use exec() with persistent globals dict
-  // JavaScript: use Node.js vm module with persistent context
-  const wrappedCode = session.language === 'python'
-    ? `exec(${JSON.stringify(code)}, _globals)`
-    : code;
-
-  const result = await executeInSandbox(wrappedCode, SANDBOX_PRESETS['code-interpreter']);
-
-  // Append to history (immutable update)
-  session.history = [...session.history, { code, result }];
-
-  return result;
-}
-
-// Rich output capture — not just stdout
-interface RichOutput {
-  text?: string;
-  images?: { data: string; mimeType: string }[];  // base64 encoded
-  tables?: { headers: string[]; rows: string[][] }[];
-  error?: string;
-}
-```
-
-**Step 5 — Security boundaries**
-Enforce isolation guarantees:
-
-| Boundary | Enforcement |
-|---|---|
-| File system | Read-only mount + tmpfs for temp files. No access to host filesystem. |
-| Network | `--network none` for code interpreter. Whitelist for build/test. |
-| Memory | Docker `--memory` limit. OOM killed if exceeded. |
-| CPU | Docker `--cpus` limit. Prevents crypto mining / infinite loops. |
-| Time | Kill process after timeout. Return partial output. |
-| Secrets | Never mount env vars or secrets into sandbox container. |
-| Output size | Cap stdout/stderr at 1MB. Truncate with `[output truncated]` marker. |
-
-#### Sharp Edges
-
-| Failure Mode | Mitigation |
-|---|---|
-| Sandbox escape via Docker vulnerability | Pin Docker version; use rootless Docker; consider gVisor/Firecracker for high-security |
-| Code writes to /tmp exhausting disk | Use `--tmpfs` with size limit (64MB default) |
-| Infinite loop inside sandbox hangs API | Hard timeout with SIGKILL — never rely on SIGTERM alone |
-| Stateful session grows unbounded memory | Limit session history to last 50 executions; reset context on overflow |
+---
+name: "code-sandbox"
+pack: "@rune/ai-ml"
+description: "Secure code execution for AI agents — sandboxed environments for running LLM-generated code safely with container isolation, resource limits, and timeout enforcement."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# code-sandbox
+
+Secure code execution for AI agents — sandboxed environments for running LLM-generated code safely. Covers container isolation, resource limits, timeout enforcement, file system boundaries, and output capture for code interpreter, CI/CD, and interactive development use cases.
+
+#### Workflow
+
+**Step 1 — Assess execution requirements**
+Determine what kind of code the agent needs to run:
+
+| Use Case | Isolation Level | Runtime |
+|---|---|---|
+| Code interpreter (data analysis, math) | High — untrusted code | Python + pandas/numpy |
+| Build/test pipeline | Medium — project code | Node.js / Python with project deps |
+| Interactive preview (web app) | Medium — expose HTTP port | Node.js + browser preview |
+| Shell commands (file ops, git) | Low — trusted context | System shell with path restrictions |
+
+**Step 2 — Configure sandbox environment**
+Emit sandbox configuration based on use case:
+
+```typescript
+// Sandbox factory — select isolation level by use case
+interface SandboxConfig {
+  language: 'python' | 'javascript' | 'typescript';
+  timeout: number;       // max execution time in ms
+  memoryLimit: number;   // max memory in MB
+  networkAccess: boolean;
+  fileSystemRoot: string;  // restricted working directory
+  allowedModules: string[];
+}
+
+const SANDBOX_PRESETS: Record<string, SandboxConfig> = {
+  'code-interpreter': {
+    language: 'python',
+    timeout: 30_000,
+    memoryLimit: 256,
+    networkAccess: false,
+    fileSystemRoot: '/workspace',
+    allowedModules: ['pandas', 'numpy', 'matplotlib', 'scipy', 'json', 'csv', 'math'],
+  },
+  'build-test': {
+    language: 'typescript',
+    timeout: 120_000,
+    memoryLimit: 512,
+    networkAccess: true,  // needs npm registry
+    fileSystemRoot: '/project',
+    allowedModules: ['*'],  // project dependencies
+  },
+  'preview': {
+    language: 'javascript',
+    timeout: 300_000,
+    memoryLimit: 256,
+    networkAccess: true,
+    fileSystemRoot: '/app',
+    allowedModules: ['*'],
+  },
+};
+```
+
+**Step 3 — Implement execution with resource limits**
+Emit code execution wrapper with safety boundaries:
+
+```typescript
+// Docker-based sandbox execution
+import { spawn } from 'child_process';
+
+interface ExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  durationMs: number;
+  timedOut: boolean;
+}
+
+async function executeInSandbox(
+  code: string,
+  config: SandboxConfig
+): Promise<ExecutionResult> {
+  const start = Date.now();
+
+  // Write code to temp file in sandbox root
+  const codePath = `${config.fileSystemRoot}/run.${config.language === 'python' ? 'py' : 'ts'}`;
+  await writeFile(codePath, code);
+
+  const proc = spawn('docker', [
+    'run', '--rm',
+    '--memory', `${config.memoryLimit}m`,
+    '--cpus', '1',
+    '--network', config.networkAccess ? 'bridge' : 'none',
+    '--read-only',
+    '--tmpfs', '/tmp:size=64m',
+    '-v', `${config.fileSystemRoot}:/workspace:ro`,
+    '-w', '/workspace',
+    `sandbox-${config.language}:latest`,
+    config.language === 'python' ? 'python' : 'npx tsx',
+    `/workspace/run.${config.language === 'python' ? 'py' : 'ts'}`,
+  ]);
+
+  let stdout = '';
+  let stderr = '';
+  let timedOut = false;
+
+  proc.stdout.on('data', (d) => { stdout += d.toString(); });
+  proc.stderr.on('data', (d) => { stderr += d.toString(); });
+
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    proc.kill('SIGKILL');
+  }, config.timeout);
+
+  const exitCode = await new Promise<number>((resolve) => {
+    proc.on('close', (code) => {
+      clearTimeout(timeout);
+      resolve(code ?? 1);
+    });
+  });
+
+  return { stdout, stderr, exitCode, durationMs: Date.now() - start, timedOut };
+}
+```
+
+**Step 4 — Code interpreter mode (stateful sessions)**
+For multi-turn code execution where variables persist between runs:
+
+```typescript
+// Stateful code interpreter — variables persist across executions
+interface CodeSession {
+  id: string;
+  language: 'python' | 'javascript';
+  history: { code: string; result: ExecutionResult }[];
+}
+
+async function runInSession(
+  session: CodeSession,
+  code: string
+): Promise<ExecutionResult> {
+  // Python: use exec() with persistent globals dict
+  // JavaScript: use Node.js vm module with persistent context
+  const wrappedCode = session.language === 'python'
+    ? `exec(${JSON.stringify(code)}, _globals)`
+    : code;
+
+  const result = await executeInSandbox(wrappedCode, SANDBOX_PRESETS['code-interpreter']);
+
+  // Append to history (immutable update)
+  session.history = [...session.history, { code, result }];
+
+  return result;
+}
+
+// Rich output capture — not just stdout
+interface RichOutput {
+  text?: string;
+  images?: { data: string; mimeType: string }[];  // base64 encoded
+  tables?: { headers: string[]; rows: string[][] }[];
+  error?: string;
+}
+```
+
+**Step 5 — Security boundaries**
+Enforce isolation guarantees:
+
+| Boundary | Enforcement |
+|---|---|
+| File system | Read-only mount + tmpfs for temp files. No access to host filesystem. |
+| Network | `--network none` for code interpreter. Whitelist for build/test. |
+| Memory | Docker `--memory` limit. OOM killed if exceeded. |
+| CPU | Docker `--cpus` limit. Prevents crypto mining / infinite loops. |
+| Time | Kill process after timeout. Return partial output. |
+| Secrets | Never mount env vars or secrets into sandbox container. |
+| Output size | Cap stdout/stderr at 1MB. Truncate with `[output truncated]` marker. |
+
+#### Sharp Edges
+
+| Failure Mode | Mitigation |
+|---|---|
+| Sandbox escape via Docker vulnerability | Pin Docker version; use rootless Docker; consider gVisor/Firecracker for high-security |
+| Code writes to /tmp exhausting disk | Use `--tmpfs` with size limit (64MB default) |
+| Infinite loop inside sandbox hangs API | Hard timeout with SIGKILL — never rely on SIGTERM alone |
+| Stateful session grows unbounded memory | Limit session history to last 50 executions; reset context on overflow |

package/extensions/ai-ml/skills/deep-research.md

@@ -1,146 +1,146 @@
----
-name: "deep-research"
-pack: "@rune/ai-ml"
-description: "Iterative AI research loop that converges on comprehensive answers — search, analyze, identify gaps, repeat. Outputs synthesized report with source attribution."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# deep-research
-
-Iterative AI research loop that converges on comprehensive answers. Search → analyze → identify gaps → search again. Bounded by depth, time, and URL limits. Outputs synthesized report with source attribution.
-
-#### Workflow
-
-**Step 1 — Initialize research state**
-```typescript
-interface ResearchState {
-  query: string;
-  findings: Finding[];           // max 50 most recent (memory bound)
-  gaps: string[];                // what we still don't know
-  seenUrls: Set<string>;         // dedup
-  failedQueries: number;         // convergence signal
-  depth: number;                 // current iteration
-  maxDepth: number;              // hard limit (default: 10)
-  maxUrls: number;               // hard limit (default: 100)
-  maxTimeMs: number;             // hard limit (default: 300_000 = 5 min)
-  startedAt: number;
-  activityLog: ActivityEntry[];  // for progress streaming
-}
-
-interface Finding {
-  content: string;
-  sourceUrl: string;
-  relevance: number;    // 0-1
-  extractedAt: number;
-}
-```
-
-**Step 2 — Generate search queries from current state**
-Each iteration, LLM generates 3 search queries based on:
-- Original research question
-- Current findings (what we know)
-- Current gaps (what we don't know)
-
-```typescript
-const queryPrompt = `Given the research question: "${state.query}"
-Current findings: ${summarizeFindings(state.findings)}
-Knowledge gaps: ${state.gaps.join(', ')}
-
-Generate 3 specific search queries that would fill the most important gaps.
-Avoid queries similar to: ${state.seenQueries.join(', ')}`;
-```
-
-**Step 3 — Search and deduplicate**
-Execute queries in parallel → collect URLs → filter against `seenUrls` → scrape new URLs → extract relevant content.
-
-```typescript
-async function searchAndExtract(queries: string[], state: ResearchState): Promise<Finding[]> {
-  // Parallel search
-  const allResults = await Promise.all(queries.map(q => webSearch(q, { limit: 10 })));
-  const urls = deduplicateUrls(allResults.flat(), state.seenUrls);
-
-  // Mark as seen immediately (even before scraping)
-  for (const url of urls) state.seenUrls.add(url);
-
-  // Scrape and extract in parallel (with concurrency limit)
-  const findings = await pMap(urls, async (url) => {
-    const content = await scrapeAndClean(url);
-    const relevance = await scoreRelevance(content, state.query);
-    return { content: summarize(content, 500), sourceUrl: url, relevance, extractedAt: Date.now() };
-  }, { concurrency: 5 });
-
-  return findings.filter(f => f.relevance > 0.3);  // threshold
-}
-```
-
-**Step 4 — Analyze findings and detect gaps**
-LLM analyzes new findings against existing knowledge:
-```typescript
-interface AnalysisResult {
-  newInsights: string[];
-  updatedGaps: string[];
-  shouldContinue: boolean;
-  nextSearchTopic: string | null;
-  confidence: number;  // 0-1: how complete is our understanding?
-}
-```
-
-**Step 5 — Check convergence criteria**
-Stop when ANY of:
-- `depth >= maxDepth`
-- `seenUrls.size >= maxUrls`
-- `Date.now() - startedAt >= maxTimeMs`
-- `gaps.length === 0` (all gaps filled)
-- `failedQueries >= 3` consecutive (no new information available)
-- `confidence >= 0.9` (LLM believes research is comprehensive)
-
-**Step 6 — Synthesize final report**
-```typescript
-interface ResearchReport {
-  question: string;
-  answer: string;              // comprehensive markdown synthesis
-  confidence: number;
-  sources: Array<{
-    url: string;
-    title: string;
-    relevance: number;
-    citedIn: string[];         // which sections cite this source
-  }>;
-  methodology: {
-    totalIterations: number;
-    urlsExamined: number;
-    findingsCount: number;
-    timeElapsed: number;
-    remainingGaps: string[];
-  };
-}
-```
-
-Memory management: keep only 50 most recent findings to avoid context explosion. Summarize older findings into a "background knowledge" string before dropping them.
-
-#### Example
-
-```typescript
-// Usage
-const report = await deepResearch({
-  query: 'What are the best practices for implementing RAG in production in 2026?',
-  maxDepth: 8,
-  maxUrls: 50,
-  maxTimeMs: 180_000,  // 3 minutes
-  onProgress: (entry) => console.log(`[${entry.depth}] ${entry.action}: ${entry.detail}`),
-});
-
-// Output: comprehensive report with 15-30 sources, gap analysis, confidence score
-```
-
-#### Sharp Edges
-
-| Failure Mode | Mitigation |
-|---|---|
-| Research loop runs forever (no convergence) | Hard limits on depth, URLs, and time; monitor `failedQueries` counter |
-| LLM generates duplicate search queries | Track seen queries; include exclusion list in prompt |
-| Memory explosion from accumulating findings | Cap at 50 findings; summarize oldest into background knowledge string |
-| Low-quality sources pollute findings | Relevance threshold (0.3); domain blocklist for known low-quality sites |
-| Rate limiting on search API | Per-provider rate limiter; fallback to alternative search provider |
-| Circular research (keeps finding same information) | Track `confidence` — if stable for 3 iterations, force stop |
+---
+name: "deep-research"
+pack: "@rune/ai-ml"
+description: "Iterative AI research loop that converges on comprehensive answers — search, analyze, identify gaps, repeat. Outputs synthesized report with source attribution."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# deep-research
+
+Iterative AI research loop that converges on comprehensive answers. Search → analyze → identify gaps → search again. Bounded by depth, time, and URL limits. Outputs synthesized report with source attribution.
+
+#### Workflow
+
+**Step 1 — Initialize research state**
+```typescript
+interface ResearchState {
+  query: string;
+  findings: Finding[];           // max 50 most recent (memory bound)
+  gaps: string[];                // what we still don't know
+  seenUrls: Set<string>;         // dedup
+  failedQueries: number;         // convergence signal
+  depth: number;                 // current iteration
+  maxDepth: number;              // hard limit (default: 10)
+  maxUrls: number;               // hard limit (default: 100)
+  maxTimeMs: number;             // hard limit (default: 300_000 = 5 min)
+  startedAt: number;
+  activityLog: ActivityEntry[];  // for progress streaming
+}
+
+interface Finding {
+  content: string;
+  sourceUrl: string;
+  relevance: number;    // 0-1
+  extractedAt: number;
+}
+```
+
+**Step 2 — Generate search queries from current state**
+Each iteration, LLM generates 3 search queries based on:
+- Original research question
+- Current findings (what we know)
+- Current gaps (what we don't know)
+
+```typescript
+const queryPrompt = `Given the research question: "${state.query}"
+Current findings: ${summarizeFindings(state.findings)}
+Knowledge gaps: ${state.gaps.join(', ')}
+
+Generate 3 specific search queries that would fill the most important gaps.
+Avoid queries similar to: ${state.seenQueries.join(', ')}`;
+```
+
+**Step 3 — Search and deduplicate**
+Execute queries in parallel → collect URLs → filter against `seenUrls` → scrape new URLs → extract relevant content.
+
+```typescript
+async function searchAndExtract(queries: string[], state: ResearchState): Promise<Finding[]> {
+  // Parallel search
+  const allResults = await Promise.all(queries.map(q => webSearch(q, { limit: 10 })));
+  const urls = deduplicateUrls(allResults.flat(), state.seenUrls);
+
+  // Mark as seen immediately (even before scraping)
+  for (const url of urls) state.seenUrls.add(url);
+
+  // Scrape and extract in parallel (with concurrency limit)
+  const findings = await pMap(urls, async (url) => {
+    const content = await scrapeAndClean(url);
+    const relevance = await scoreRelevance(content, state.query);
+    return { content: summarize(content, 500), sourceUrl: url, relevance, extractedAt: Date.now() };
+  }, { concurrency: 5 });
+
+  return findings.filter(f => f.relevance > 0.3);  // threshold
+}
+```
+
+**Step 4 — Analyze findings and detect gaps**
+LLM analyzes new findings against existing knowledge:
+```typescript
+interface AnalysisResult {
+  newInsights: string[];
+  updatedGaps: string[];
+  shouldContinue: boolean;
+  nextSearchTopic: string | null;
+  confidence: number;  // 0-1: how complete is our understanding?
+}
+```
+
+**Step 5 — Check convergence criteria**
+Stop when ANY of:
+- `depth >= maxDepth`
+- `seenUrls.size >= maxUrls`
+- `Date.now() - startedAt >= maxTimeMs`
+- `gaps.length === 0` (all gaps filled)
+- `failedQueries >= 3` consecutive (no new information available)
+- `confidence >= 0.9` (LLM believes research is comprehensive)
+
+**Step 6 — Synthesize final report**
+```typescript
+interface ResearchReport {
+  question: string;
+  answer: string;              // comprehensive markdown synthesis
+  confidence: number;
+  sources: Array<{
+    url: string;
+    title: string;
+    relevance: number;
+    citedIn: string[];         // which sections cite this source
+  }>;
+  methodology: {
+    totalIterations: number;
+    urlsExamined: number;
+    findingsCount: number;
+    timeElapsed: number;
+    remainingGaps: string[];
+  };
+}
+```
+
+Memory management: keep only 50 most recent findings to avoid context explosion. Summarize older findings into a "background knowledge" string before dropping them.
+
+#### Example
+
+```typescript
+// Usage
+const report = await deepResearch({
+  query: 'What are the best practices for implementing RAG in production in 2026?',
+  maxDepth: 8,
+  maxUrls: 50,
+  maxTimeMs: 180_000,  // 3 minutes
+  onProgress: (entry) => console.log(`[${entry.depth}] ${entry.action}: ${entry.detail}`),
+});
+
+// Output: comprehensive report with 15-30 sources, gap analysis, confidence score
+```
+
+#### Sharp Edges
+
+| Failure Mode | Mitigation |
+|---|---|
+| Research loop runs forever (no convergence) | Hard limits on depth, URLs, and time; monitor `failedQueries` counter |
+| LLM generates duplicate search queries | Track seen queries; include exclusion list in prompt |
+| Memory explosion from accumulating findings | Cap at 50 findings; summarize oldest into background knowledge string |
+| Low-quality sources pollute findings | Relevance threshold (0.3); domain blocklist for known low-quality sites |
+| Rate limiting on search API | Per-provider rate limiter; fallback to alternative search provider |
+| Circular research (keeps finding same information) | Track `confidence` — if stable for 3 iterations, force stop |