@rune-kit/rune 2.2.0 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. package/README.md +72 -40
  2. package/compiler/__tests__/pack-split.test.js +145 -0
  3. package/compiler/bin/rune.js +26 -9
  4. package/compiler/doctor.js +42 -0
  5. package/compiler/emitter.js +27 -4
  6. package/compiler/parser.js +41 -3
  7. package/compiler/transformer.js +10 -6
  8. package/compiler/transforms/compliance.js +40 -0
  9. package/docs/ANTIGRAVITY-GAP-ANALYSIS.md +369 -0
  10. package/docs/ARCHITECTURE.md +332 -0
  11. package/docs/COMMUNITY-PACKS.md +109 -0
  12. package/docs/CONTRIBUTING-L4.md +215 -0
  13. package/docs/CROSS-IDE-ANALYSIS.md +164 -0
  14. package/docs/EXTENSION-TEMPLATE.md +108 -0
  15. package/docs/MESH-RULES.md +34 -0
  16. package/docs/MULTI-PLATFORM.md +804 -0
  17. package/docs/SKILL-DEPTH-AUDIT.md +191 -0
  18. package/docs/SKILL-TEMPLATE.md +72 -0
  19. package/docs/TRADE-MATRIX.md +327 -0
  20. package/docs/VERSIONING.md +91 -0
  21. package/docs/VISION.md +263 -0
  22. package/docs/assets/demo-subtitles.srt +215 -0
  23. package/docs/assets/end-card.html +276 -0
  24. package/docs/assets/mesh-diagram.html +654 -0
  25. package/docs/assets/thumbnail.html +295 -0
  26. package/docs/guides/cli.md +403 -0
  27. package/docs/guides/index.html +1346 -0
  28. package/docs/index.html +674 -0
  29. package/docs/references/claudekit-analysis.md +414 -0
  30. package/docs/references/voltagent-analysis.md +189 -0
  31. package/docs/script.js +277 -0
  32. package/docs/skills/index.html +832 -0
  33. package/docs/style.css +583 -0
  34. package/docs/video-demo-plan.md +172 -0
  35. package/extensions/ai-ml/PACK.md +38 -474
  36. package/extensions/ai-ml/skills/ai-agents.md +172 -0
  37. package/extensions/ai-ml/skills/code-sandbox.md +187 -0
  38. package/extensions/ai-ml/skills/deep-research.md +146 -0
  39. package/extensions/ai-ml/skills/embedding-search.md +66 -0
  40. package/extensions/ai-ml/skills/fine-tuning-guide.md +74 -0
  41. package/extensions/ai-ml/skills/llm-architect.md +125 -0
  42. package/extensions/ai-ml/skills/llm-integration.md +64 -0
  43. package/extensions/ai-ml/skills/prompt-patterns.md +72 -0
  44. package/extensions/ai-ml/skills/rag-patterns.md +66 -0
  45. package/extensions/ai-ml/skills/web-extraction.md +114 -0
  46. package/extensions/analytics/PACK.md +19 -484
  47. package/extensions/analytics/skills/ab-testing.md +72 -0
  48. package/extensions/analytics/skills/dashboard-patterns.md +83 -0
  49. package/extensions/analytics/skills/data-validation.md +68 -0
  50. package/extensions/analytics/skills/funnel-analysis.md +81 -0
  51. package/extensions/analytics/skills/sql-patterns.md +57 -0
  52. package/extensions/analytics/skills/statistical-analysis.md +79 -0
  53. package/extensions/analytics/skills/tracking-setup.md +71 -0
  54. package/extensions/backend/PACK.md +44 -618
  55. package/extensions/backend/skills/api-patterns.md +84 -0
  56. package/extensions/backend/skills/async-pipeline.md +193 -0
  57. package/extensions/backend/skills/auth-patterns.md +97 -0
  58. package/extensions/backend/skills/background-jobs.md +133 -0
  59. package/extensions/backend/skills/caching-patterns.md +108 -0
  60. package/extensions/backend/skills/cli-generation.md +133 -0
  61. package/extensions/backend/skills/database-patterns.md +87 -0
  62. package/extensions/backend/skills/middleware-patterns.md +104 -0
  63. package/extensions/chrome-ext/PACK.md +19 -921
  64. package/extensions/chrome-ext/skills/cws-preflight.md +143 -0
  65. package/extensions/chrome-ext/skills/cws-publish.md +104 -0
  66. package/extensions/chrome-ext/skills/ext-ai-integration.md +251 -0
  67. package/extensions/chrome-ext/skills/ext-messaging.md +139 -0
  68. package/extensions/chrome-ext/skills/ext-storage.md +133 -0
  69. package/extensions/chrome-ext/skills/mv3-scaffold.md +164 -0
  70. package/extensions/content/PACK.md +43 -335
  71. package/extensions/content/skills/blog-patterns.md +88 -0
  72. package/extensions/content/skills/cms-integration.md +131 -0
  73. package/extensions/content/skills/content-scoring.md +107 -0
  74. package/extensions/content/skills/i18n.md +83 -0
  75. package/extensions/content/skills/mdx-authoring.md +137 -0
  76. package/extensions/content/skills/reference.md +1014 -0
  77. package/extensions/content/skills/seo-patterns.md +67 -0
  78. package/extensions/content/skills/video-repurpose.md +153 -0
  79. package/extensions/devops/PACK.md +38 -457
  80. package/extensions/devops/skills/chaos-testing.md +67 -0
  81. package/extensions/devops/skills/ci-cd.md +75 -0
  82. package/extensions/devops/skills/docker.md +58 -0
  83. package/extensions/devops/skills/edge-serverless.md +163 -0
  84. package/extensions/devops/skills/infra-as-code.md +158 -0
  85. package/extensions/devops/skills/kubernetes.md +110 -0
  86. package/extensions/devops/skills/monitoring.md +57 -0
  87. package/extensions/devops/skills/server-setup.md +64 -0
  88. package/extensions/devops/skills/ssl-domain.md +42 -0
  89. package/extensions/ecommerce/PACK.md +62 -226
  90. package/extensions/ecommerce/skills/cart-system.md +79 -0
  91. package/extensions/ecommerce/skills/inventory-mgmt.md +102 -0
  92. package/extensions/ecommerce/skills/order-management.md +126 -0
  93. package/extensions/ecommerce/skills/payment-integration.md +472 -0
  94. package/extensions/ecommerce/skills/shopify-dev.md +69 -0
  95. package/extensions/ecommerce/skills/subscription-billing.md +93 -0
  96. package/extensions/ecommerce/skills/tax-compliance.md +117 -0
  97. package/extensions/gamedev/PACK.md +66 -317
  98. package/extensions/gamedev/skills/asset-pipeline.md +74 -0
  99. package/extensions/gamedev/skills/audio-system.md +129 -0
  100. package/extensions/gamedev/skills/camera-system.md +87 -0
  101. package/extensions/gamedev/skills/ecs.md +98 -0
  102. package/extensions/gamedev/skills/game-loops.md +72 -0
  103. package/extensions/gamedev/skills/input-system.md +199 -0
  104. package/extensions/gamedev/skills/multiplayer.md +180 -0
  105. package/extensions/gamedev/skills/particles.md +105 -0
  106. package/extensions/gamedev/skills/physics-engine.md +89 -0
  107. package/extensions/gamedev/skills/scene-management.md +146 -0
  108. package/extensions/gamedev/skills/threejs-patterns.md +90 -0
  109. package/extensions/gamedev/skills/webgl.md +71 -0
  110. package/extensions/mobile/PACK.md +56 -223
  111. package/extensions/mobile/skills/app-store-connect.md +152 -0
  112. package/extensions/mobile/skills/app-store-prep.md +66 -0
  113. package/extensions/mobile/skills/deep-linking.md +109 -0
  114. package/extensions/mobile/skills/flutter.md +60 -0
  115. package/extensions/mobile/skills/ios-build-pipeline.md +142 -0
  116. package/extensions/mobile/skills/native-bridge.md +66 -0
  117. package/extensions/mobile/skills/ota-updates.md +97 -0
  118. package/extensions/mobile/skills/push-notifications.md +111 -0
  119. package/extensions/mobile/skills/react-native.md +82 -0
  120. package/extensions/saas/PACK.md +26 -720
  121. package/extensions/saas/skills/billing-integration.md +121 -0
  122. package/extensions/saas/skills/feature-flags.md +130 -0
  123. package/extensions/saas/skills/multi-tenant.md +103 -0
  124. package/extensions/saas/skills/onboarding-flow.md +139 -0
  125. package/extensions/saas/skills/subscription-flow.md +95 -0
  126. package/extensions/saas/skills/team-management.md +144 -0
  127. package/extensions/security/PACK.md +10 -448
  128. package/extensions/security/skills/api-security.md +140 -0
  129. package/extensions/security/skills/compliance.md +68 -0
  130. package/extensions/security/skills/owasp-audit.md +64 -0
  131. package/extensions/security/skills/pentest-patterns.md +77 -0
  132. package/extensions/security/skills/secret-mgmt.md +65 -0
  133. package/extensions/security/skills/supply-chain.md +65 -0
  134. package/extensions/trading/PACK.md +18 -535
  135. package/extensions/trading/skills/chart-components.md +55 -0
  136. package/extensions/trading/skills/experiment-loop.md +125 -0
  137. package/extensions/trading/skills/fintech-patterns.md +47 -0
  138. package/extensions/trading/skills/indicator-library.md +58 -0
  139. package/extensions/trading/skills/quant-analysis.md +111 -0
  140. package/extensions/trading/skills/realtime-data.md +58 -0
  141. package/extensions/trading/skills/trade-logic.md +104 -0
  142. package/extensions/ui/PACK.md +36 -853
  143. package/extensions/ui/skills/a11y-audit.md +91 -0
  144. package/extensions/ui/skills/animation-patterns.md +106 -0
  145. package/extensions/ui/skills/component-patterns.md +75 -0
  146. package/extensions/ui/skills/design-decision.md +108 -0
  147. package/extensions/ui/skills/design-system.md +68 -0
  148. package/extensions/ui/skills/landing-patterns.md +155 -0
  149. package/extensions/ui/skills/palette-picker.md +173 -0
  150. package/extensions/ui/skills/react-health.md +90 -0
  151. package/extensions/ui/skills/type-system.md +125 -0
  152. package/extensions/ui/skills/web-vitals.md +153 -0
  153. package/extensions/zalo/PACK.md +117 -0
  154. package/extensions/zalo/skills/zalo-oa-mcp.md +317 -0
  155. package/extensions/zalo/skills/zalo-oa-messaging.md +429 -0
  156. package/extensions/zalo/skills/zalo-oa-setup.md +236 -0
  157. package/extensions/zalo/skills/zalo-oa-webhook.md +189 -0
  158. package/extensions/zalo/skills/zalo-personal-messaging.md +194 -0
  159. package/extensions/zalo/skills/zalo-personal-setup.md +153 -0
  160. package/extensions/zalo/skills/zalo-rate-guard.md +219 -0
  161. package/hooks/.gitkeep +0 -0
  162. package/hooks/auto-format/index.cjs +48 -0
  163. package/hooks/context-watch/index.cjs +68 -0
  164. package/hooks/hooks.json +99 -0
  165. package/hooks/metrics-collector/index.cjs +42 -0
  166. package/hooks/post-session-reflect/index.cjs +153 -0
  167. package/hooks/pre-compact/index.cjs +95 -0
  168. package/hooks/pre-tool-guard/index.cjs +68 -0
  169. package/hooks/run-hook +17 -0
  170. package/hooks/run-hook.cjs +16 -0
  171. package/hooks/run-hook.cmd +1 -0
  172. package/hooks/secrets-scan/index.cjs +100 -0
  173. package/hooks/session-start/index.cjs +65 -0
  174. package/hooks/typecheck/index.cjs +65 -0
  175. package/package.json +9 -4
  176. package/references/ui-pro-max-data/LICENSE-UI-PRO-MAX +21 -0
  177. package/references/ui-pro-max-data/charts.csv +26 -0
  178. package/references/ui-pro-max-data/colors.csv +162 -0
  179. package/references/ui-pro-max-data/styles.csv +85 -0
  180. package/references/ui-pro-max-data/typography.csv +74 -0
  181. package/references/ui-pro-max-data/ui-reasoning.csv +162 -0
  182. package/references/ui-pro-max-data/ux-guidelines.csv +100 -0
  183. package/skills/ba/SKILL.md +10 -0
  184. package/skills/brainstorm/SKILL.md +63 -1
  185. package/skills/completion-gate/SKILL.md +34 -1
  186. package/skills/context-engine/SKILL.md +13 -0
  187. package/skills/cook/SKILL.md +155 -5
  188. package/skills/debug/SKILL.md +56 -1
  189. package/skills/design/SKILL.md +11 -0
  190. package/skills/fix/SKILL.md +26 -1
  191. package/skills/mcp-builder/SKILL.md +48 -1
  192. package/skills/plan/SKILL.md +23 -6
  193. package/skills/review/SKILL.md +44 -5
  194. package/skills/review-intake/SKILL.md +17 -1
  195. package/skills/skill-forge/SKILL.md +38 -3
  196. package/skills/skill-router/SKILL.md +89 -7
  197. package/skills/team/SKILL.md +24 -1
  198. package/skills/test/SKILL.md +28 -1
  199. package/skills/verification/SKILL.md +98 -1
@@ -0,0 +1,172 @@
1
+ ---
2
+ name: "ai-agents"
3
+ pack: "@rune/ai-ml"
4
+ description: "Stateful AI agent architecture — persistent state, callable RPC methods, scheduling, multi-agent coordination, MCP server integration, and real-time client communication via WebSocket."
5
+ model: sonnet
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ ---
8
+
9
+ # ai-agents
10
+
11
+ Stateful AI agent architecture — persistent state, callable RPC methods, scheduling, multi-agent coordination, MCP server integration, and real-time client communication via WebSocket. Covers agent lifecycle, state management patterns, tool registration, human-in-the-loop approval flows, and durable workflow orchestration for long-running agent tasks.
12
+
13
+ #### Workflow
14
+
15
+ **Step 1 — Classify agent type**
16
+ Identify what the agent needs to do and map to an architecture:
17
+
18
+ | Agent Type | Key Characteristics | Platform Options |
19
+ |---|---|---|
20
+ | Stateless tool-caller | Single request → tool calls → response. No memory between requests. | Any LLM API + function calling |
21
+ | Conversational with memory | Multi-turn dialogue. Needs chat history persistence. | Session store (Redis, KV) + LLM |
22
+ | Stateful autonomous | Persistent state, scheduled tasks, reacts to events. Long-lived. | Cloudflare Agents SDK, LangGraph, CrewAI |
23
+ | Multi-agent coordinator | Multiple specialized agents collaborating on a task. | LangGraph, AutoGen, custom orchestrator |
24
+ | MCP server | Exposes tools/resources to any MCP-compatible client. | Cloudflare McpAgent, custom MCP server |
25
+
26
+ **Step 2 — Design state management**
27
+ For stateful agents, define the state contract:
28
+
29
+ ```typescript
30
+ // State must be serializable (JSON-safe) — no functions, no circular refs
31
+ interface AgentState {
32
+ // Domain state
33
+ conversations: ConversationEntry[];
34
+ preferences: Record<string, string>;
35
+ taskQueue: ScheduledTask[];
36
+
37
+ // Metadata
38
+ createdAt: string;
39
+ lastActiveAt: string;
40
+ version: number;
41
+ }
42
+
43
+ // State validation — reject invalid transitions
44
+ function validateStateChange(current: AgentState, next: AgentState): void {
45
+ if (next.version < current.version) {
46
+ throw new Error('State version cannot decrease — concurrent modification detected');
47
+ }
48
+ if (next.conversations.length > 10_000) {
49
+ throw new Error('Conversation limit exceeded — archive old entries first');
50
+ }
51
+ }
52
+ ```
53
+
54
+ **Step 3 — Implement tool registration**
55
+ Define agent capabilities as typed, callable methods:
56
+
57
+ ```typescript
58
+ // Tools as typed RPC methods (Cloudflare Agents SDK pattern)
59
+ import { Agent, callable } from 'agents';
60
+
61
+ export class ResearchAgent extends Agent<Env, ResearchState> {
62
+ initialState: ResearchState = { findings: [], status: 'idle' };
63
+
64
+ @callable()
65
+ async search(query: string): Promise<SearchResult[]> {
66
+ this.setState({ ...this.state, status: 'searching' });
67
+ const results = await this.env.AI.run('@cf/meta/llama-3-8b-instruct', {
68
+ prompt: `Search for: ${query}`,
69
+ });
70
+ const findings = parseResults(results);
71
+ this.setState({
72
+ ...this.state,
73
+ findings: [...this.state.findings, ...findings],
74
+ status: 'idle',
75
+ });
76
+ return findings;
77
+ }
78
+
79
+ @callable()
80
+ async summarize(): Promise<string> {
81
+ if (this.state.findings.length === 0) {
82
+ throw new Error('No findings to summarize — run search first');
83
+ }
84
+ return generateSummary(this.state.findings);
85
+ }
86
+ }
87
+ ```
88
+
89
+ **Step 4 — Add scheduling and durability**
90
+ For agents that need to perform work on a schedule or survive restarts:
91
+
92
+ ```typescript
93
+ // Scheduled tasks — one-time, recurring, and cron
94
+ @callable()
95
+ async scheduleDigest(userId: string) {
96
+ // Daily digest at 9 AM
97
+ await this.schedule('0 9 * * *', 'sendDigest', { userId });
98
+
99
+ // One-time reminder in 1 hour
100
+ await this.schedule(3600, 'sendReminder', { userId, message: 'Check results' });
101
+
102
+ // Recurring every 30 minutes
103
+ await this.scheduleEvery(1800, 'pollDataSource');
104
+ }
105
+
106
+ // Handler runs when scheduled time arrives — even if agent was hibernated
107
+ async onScheduledTask(task: ScheduledTask) {
108
+ switch (task.type) {
109
+ case 'sendDigest':
110
+ await this.compileAndSendDigest(task.payload.userId);
111
+ break;
112
+ case 'pollDataSource':
113
+ const newData = await fetchLatest();
114
+ if (newData.length > 0) {
115
+ this.setState({ ...this.state, lastPoll: Date.now(), data: newData });
116
+ }
117
+ break;
118
+ }
119
+ }
120
+ ```
121
+
122
+ **Step 5 — Human-in-the-loop patterns**
123
+ For agents that need approval before taking high-impact actions:
124
+
125
+ ```typescript
126
+ // Approval flow — agent pauses, human approves, agent resumes
127
+ interface PendingApproval {
128
+ id: string;
129
+ action: string;
130
+ params: Record<string, unknown>;
131
+ requestedAt: string;
132
+ status: 'pending' | 'approved' | 'rejected';
133
+ }
134
+
135
+ @callable()
136
+ async requestApproval(action: string, params: Record<string, unknown>): Promise<string> {
137
+ const approval: PendingApproval = {
138
+ id: crypto.randomUUID(),
139
+ action,
140
+ params,
141
+ requestedAt: new Date().toISOString(),
142
+ status: 'pending',
143
+ };
144
+ this.setState({
145
+ ...this.state,
146
+ pendingApprovals: [...this.state.pendingApprovals, approval],
147
+ });
148
+ // Client receives state update via WebSocket → shows approval UI
149
+ return approval.id;
150
+ }
151
+
152
+ @callable()
153
+ async resolveApproval(id: string, decision: 'approved' | 'rejected') {
154
+ const updated = this.state.pendingApprovals.map(a =>
155
+ a.id === id ? { ...a, status: decision } : a
156
+ );
157
+ this.setState({ ...this.state, pendingApprovals: updated });
158
+ if (decision === 'approved') {
159
+ const approval = updated.find(a => a.id === id)!;
160
+ await this.executeAction(approval.action, approval.params);
161
+ }
162
+ }
163
+ ```
164
+
165
+ #### Sharp Edges
166
+
167
+ | Failure Mode | Mitigation |
168
+ |---|---|
169
+ | State grows unbounded (conversation history, logs) | Implement max size limits with archival; prune old entries on state update |
170
+ | Concurrent state mutations from multiple clients | Use version counter in state; reject updates with stale version |
171
+ | Agent crashes mid-workflow, loses progress | Use durable workflows (Cloudflare Workflows, Temporal) for multi-step tasks — each step is persisted |
172
+ | Scheduled tasks pile up during agent hibernation | Deduplicate on wake-up; use idempotency keys for task handlers |
@@ -0,0 +1,187 @@
1
+ ---
2
+ name: "code-sandbox"
3
+ pack: "@rune/ai-ml"
4
+ description: "Secure code execution for AI agents — sandboxed environments for running LLM-generated code safely with container isolation, resource limits, and timeout enforcement."
5
+ model: sonnet
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ ---
8
+
9
+ # code-sandbox
10
+
11
+ 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.
12
+
13
+ #### Workflow
14
+
15
+ **Step 1 — Assess execution requirements**
16
+ Determine what kind of code the agent needs to run:
17
+
18
+ | Use Case | Isolation Level | Runtime |
19
+ |---|---|---|
20
+ | Code interpreter (data analysis, math) | High — untrusted code | Python + pandas/numpy |
21
+ | Build/test pipeline | Medium — project code | Node.js / Python with project deps |
22
+ | Interactive preview (web app) | Medium — expose HTTP port | Node.js + browser preview |
23
+ | Shell commands (file ops, git) | Low — trusted context | System shell with path restrictions |
24
+
25
+ **Step 2 — Configure sandbox environment**
26
+ Emit sandbox configuration based on use case:
27
+
28
+ ```typescript
29
+ // Sandbox factory — select isolation level by use case
30
+ interface SandboxConfig {
31
+ language: 'python' | 'javascript' | 'typescript';
32
+ timeout: number; // max execution time in ms
33
+ memoryLimit: number; // max memory in MB
34
+ networkAccess: boolean;
35
+ fileSystemRoot: string; // restricted working directory
36
+ allowedModules: string[];
37
+ }
38
+
39
+ const SANDBOX_PRESETS: Record<string, SandboxConfig> = {
40
+ 'code-interpreter': {
41
+ language: 'python',
42
+ timeout: 30_000,
43
+ memoryLimit: 256,
44
+ networkAccess: false,
45
+ fileSystemRoot: '/workspace',
46
+ allowedModules: ['pandas', 'numpy', 'matplotlib', 'scipy', 'json', 'csv', 'math'],
47
+ },
48
+ 'build-test': {
49
+ language: 'typescript',
50
+ timeout: 120_000,
51
+ memoryLimit: 512,
52
+ networkAccess: true, // needs npm registry
53
+ fileSystemRoot: '/project',
54
+ allowedModules: ['*'], // project dependencies
55
+ },
56
+ 'preview': {
57
+ language: 'javascript',
58
+ timeout: 300_000,
59
+ memoryLimit: 256,
60
+ networkAccess: true,
61
+ fileSystemRoot: '/app',
62
+ allowedModules: ['*'],
63
+ },
64
+ };
65
+ ```
66
+
67
+ **Step 3 — Implement execution with resource limits**
68
+ Emit code execution wrapper with safety boundaries:
69
+
70
+ ```typescript
71
+ // Docker-based sandbox execution
72
+ import { spawn } from 'child_process';
73
+
74
+ interface ExecutionResult {
75
+ stdout: string;
76
+ stderr: string;
77
+ exitCode: number;
78
+ durationMs: number;
79
+ timedOut: boolean;
80
+ }
81
+
82
+ async function executeInSandbox(
83
+ code: string,
84
+ config: SandboxConfig
85
+ ): Promise<ExecutionResult> {
86
+ const start = Date.now();
87
+
88
+ // Write code to temp file in sandbox root
89
+ const codePath = `${config.fileSystemRoot}/run.${config.language === 'python' ? 'py' : 'ts'}`;
90
+ await writeFile(codePath, code);
91
+
92
+ const proc = spawn('docker', [
93
+ 'run', '--rm',
94
+ '--memory', `${config.memoryLimit}m`,
95
+ '--cpus', '1',
96
+ '--network', config.networkAccess ? 'bridge' : 'none',
97
+ '--read-only',
98
+ '--tmpfs', '/tmp:size=64m',
99
+ '-v', `${config.fileSystemRoot}:/workspace:ro`,
100
+ '-w', '/workspace',
101
+ `sandbox-${config.language}:latest`,
102
+ config.language === 'python' ? 'python' : 'npx tsx',
103
+ `/workspace/run.${config.language === 'python' ? 'py' : 'ts'}`,
104
+ ]);
105
+
106
+ let stdout = '';
107
+ let stderr = '';
108
+ let timedOut = false;
109
+
110
+ proc.stdout.on('data', (d) => { stdout += d.toString(); });
111
+ proc.stderr.on('data', (d) => { stderr += d.toString(); });
112
+
113
+ const timeout = setTimeout(() => {
114
+ timedOut = true;
115
+ proc.kill('SIGKILL');
116
+ }, config.timeout);
117
+
118
+ const exitCode = await new Promise<number>((resolve) => {
119
+ proc.on('close', (code) => {
120
+ clearTimeout(timeout);
121
+ resolve(code ?? 1);
122
+ });
123
+ });
124
+
125
+ return { stdout, stderr, exitCode, durationMs: Date.now() - start, timedOut };
126
+ }
127
+ ```
128
+
129
+ **Step 4 — Code interpreter mode (stateful sessions)**
130
+ For multi-turn code execution where variables persist between runs:
131
+
132
+ ```typescript
133
+ // Stateful code interpreter — variables persist across executions
134
+ interface CodeSession {
135
+ id: string;
136
+ language: 'python' | 'javascript';
137
+ history: { code: string; result: ExecutionResult }[];
138
+ }
139
+
140
+ async function runInSession(
141
+ session: CodeSession,
142
+ code: string
143
+ ): Promise<ExecutionResult> {
144
+ // Python: use exec() with persistent globals dict
145
+ // JavaScript: use Node.js vm module with persistent context
146
+ const wrappedCode = session.language === 'python'
147
+ ? `exec(${JSON.stringify(code)}, _globals)`
148
+ : code;
149
+
150
+ const result = await executeInSandbox(wrappedCode, SANDBOX_PRESETS['code-interpreter']);
151
+
152
+ // Append to history (immutable update)
153
+ session.history = [...session.history, { code, result }];
154
+
155
+ return result;
156
+ }
157
+
158
+ // Rich output capture — not just stdout
159
+ interface RichOutput {
160
+ text?: string;
161
+ images?: { data: string; mimeType: string }[]; // base64 encoded
162
+ tables?: { headers: string[]; rows: string[][] }[];
163
+ error?: string;
164
+ }
165
+ ```
166
+
167
+ **Step 5 — Security boundaries**
168
+ Enforce isolation guarantees:
169
+
170
+ | Boundary | Enforcement |
171
+ |---|---|
172
+ | File system | Read-only mount + tmpfs for temp files. No access to host filesystem. |
173
+ | Network | `--network none` for code interpreter. Whitelist for build/test. |
174
+ | Memory | Docker `--memory` limit. OOM killed if exceeded. |
175
+ | CPU | Docker `--cpus` limit. Prevents crypto mining / infinite loops. |
176
+ | Time | Kill process after timeout. Return partial output. |
177
+ | Secrets | Never mount env vars or secrets into sandbox container. |
178
+ | Output size | Cap stdout/stderr at 1MB. Truncate with `[output truncated]` marker. |
179
+
180
+ #### Sharp Edges
181
+
182
+ | Failure Mode | Mitigation |
183
+ |---|---|
184
+ | Sandbox escape via Docker vulnerability | Pin Docker version; use rootless Docker; consider gVisor/Firecracker for high-security |
185
+ | Code writes to /tmp exhausting disk | Use `--tmpfs` with size limit (64MB default) |
186
+ | Infinite loop inside sandbox hangs API | Hard timeout with SIGKILL — never rely on SIGTERM alone |
187
+ | Stateful session grows unbounded memory | Limit session history to last 50 executions; reset context on overflow |
@@ -0,0 +1,146 @@
1
+ ---
2
+ name: "deep-research"
3
+ pack: "@rune/ai-ml"
4
+ description: "Iterative AI research loop that converges on comprehensive answers — search, analyze, identify gaps, repeat. Outputs synthesized report with source attribution."
5
+ model: sonnet
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ ---
8
+
9
+ # deep-research
10
+
11
+ 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.
12
+
13
+ #### Workflow
14
+
15
+ **Step 1 — Initialize research state**
16
+ ```typescript
17
+ interface ResearchState {
18
+ query: string;
19
+ findings: Finding[]; // max 50 most recent (memory bound)
20
+ gaps: string[]; // what we still don't know
21
+ seenUrls: Set<string>; // dedup
22
+ failedQueries: number; // convergence signal
23
+ depth: number; // current iteration
24
+ maxDepth: number; // hard limit (default: 10)
25
+ maxUrls: number; // hard limit (default: 100)
26
+ maxTimeMs: number; // hard limit (default: 300_000 = 5 min)
27
+ startedAt: number;
28
+ activityLog: ActivityEntry[]; // for progress streaming
29
+ }
30
+
31
+ interface Finding {
32
+ content: string;
33
+ sourceUrl: string;
34
+ relevance: number; // 0-1
35
+ extractedAt: number;
36
+ }
37
+ ```
38
+
39
+ **Step 2 — Generate search queries from current state**
40
+ Each iteration, LLM generates 3 search queries based on:
41
+ - Original research question
42
+ - Current findings (what we know)
43
+ - Current gaps (what we don't know)
44
+
45
+ ```typescript
46
+ const queryPrompt = `Given the research question: "${state.query}"
47
+ Current findings: ${summarizeFindings(state.findings)}
48
+ Knowledge gaps: ${state.gaps.join(', ')}
49
+
50
+ Generate 3 specific search queries that would fill the most important gaps.
51
+ Avoid queries similar to: ${state.seenQueries.join(', ')}`;
52
+ ```
53
+
54
+ **Step 3 — Search and deduplicate**
55
+ Execute queries in parallel → collect URLs → filter against `seenUrls` → scrape new URLs → extract relevant content.
56
+
57
+ ```typescript
58
+ async function searchAndExtract(queries: string[], state: ResearchState): Promise<Finding[]> {
59
+ // Parallel search
60
+ const allResults = await Promise.all(queries.map(q => webSearch(q, { limit: 10 })));
61
+ const urls = deduplicateUrls(allResults.flat(), state.seenUrls);
62
+
63
+ // Mark as seen immediately (even before scraping)
64
+ for (const url of urls) state.seenUrls.add(url);
65
+
66
+ // Scrape and extract in parallel (with concurrency limit)
67
+ const findings = await pMap(urls, async (url) => {
68
+ const content = await scrapeAndClean(url);
69
+ const relevance = await scoreRelevance(content, state.query);
70
+ return { content: summarize(content, 500), sourceUrl: url, relevance, extractedAt: Date.now() };
71
+ }, { concurrency: 5 });
72
+
73
+ return findings.filter(f => f.relevance > 0.3); // threshold
74
+ }
75
+ ```
76
+
77
+ **Step 4 — Analyze findings and detect gaps**
78
+ LLM analyzes new findings against existing knowledge:
79
+ ```typescript
80
+ interface AnalysisResult {
81
+ newInsights: string[];
82
+ updatedGaps: string[];
83
+ shouldContinue: boolean;
84
+ nextSearchTopic: string | null;
85
+ confidence: number; // 0-1: how complete is our understanding?
86
+ }
87
+ ```
88
+
89
+ **Step 5 — Check convergence criteria**
90
+ Stop when ANY of:
91
+ - `depth >= maxDepth`
92
+ - `seenUrls.size >= maxUrls`
93
+ - `Date.now() - startedAt >= maxTimeMs`
94
+ - `gaps.length === 0` (all gaps filled)
95
+ - `failedQueries >= 3` consecutive (no new information available)
96
+ - `confidence >= 0.9` (LLM believes research is comprehensive)
97
+
98
+ **Step 6 — Synthesize final report**
99
+ ```typescript
100
+ interface ResearchReport {
101
+ question: string;
102
+ answer: string; // comprehensive markdown synthesis
103
+ confidence: number;
104
+ sources: Array<{
105
+ url: string;
106
+ title: string;
107
+ relevance: number;
108
+ citedIn: string[]; // which sections cite this source
109
+ }>;
110
+ methodology: {
111
+ totalIterations: number;
112
+ urlsExamined: number;
113
+ findingsCount: number;
114
+ timeElapsed: number;
115
+ remainingGaps: string[];
116
+ };
117
+ }
118
+ ```
119
+
120
+ Memory management: keep only 50 most recent findings to avoid context explosion. Summarize older findings into a "background knowledge" string before dropping them.
121
+
122
+ #### Example
123
+
124
+ ```typescript
125
+ // Usage
126
+ const report = await deepResearch({
127
+ query: 'What are the best practices for implementing RAG in production in 2026?',
128
+ maxDepth: 8,
129
+ maxUrls: 50,
130
+ maxTimeMs: 180_000, // 3 minutes
131
+ onProgress: (entry) => console.log(`[${entry.depth}] ${entry.action}: ${entry.detail}`),
132
+ });
133
+
134
+ // Output: comprehensive report with 15-30 sources, gap analysis, confidence score
135
+ ```
136
+
137
+ #### Sharp Edges
138
+
139
+ | Failure Mode | Mitigation |
140
+ |---|---|
141
+ | Research loop runs forever (no convergence) | Hard limits on depth, URLs, and time; monitor `failedQueries` counter |
142
+ | LLM generates duplicate search queries | Track seen queries; include exclusion list in prompt |
143
+ | Memory explosion from accumulating findings | Cap at 50 findings; summarize oldest into background knowledge string |
144
+ | Low-quality sources pollute findings | Relevance threshold (0.3); domain blocklist for known low-quality sites |
145
+ | Rate limiting on search API | Per-provider rate limiter; fallback to alternative search provider |
146
+ | Circular research (keeps finding same information) | Track `confidence` — if stable for 3 iterations, force stop |
@@ -0,0 +1,66 @@
1
+ ---
2
+ name: "embedding-search"
3
+ pack: "@rune/ai-ml"
4
+ description: "Embedding-based search — semantic search, hybrid search (BM25 + vector), similarity thresholds, index optimization."
5
+ model: sonnet
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ ---
8
+
9
+ # embedding-search
10
+
11
+ Embedding-based search — semantic search, hybrid search (BM25 + vector), similarity thresholds, index optimization.
12
+
13
+ #### Workflow
14
+
15
+ **Step 1 — Detect search implementation**
16
+ Use Grep to find search code: `similarity_search`, `vector_search`, `fts`, `tsvector`, `BM25`. Read search handlers to understand: query flow, ranking strategy, and result formatting.
17
+
18
+ **Step 2 — Audit search quality**
19
+ Check for: pure vector search without keyword fallback (misses exact matches), no similarity threshold (returns irrelevant results at low scores), missing query embedding cache (repeated queries re-embed), no hybrid scoring (BM25 for exact + vector for semantic), and unoptimized vector index (HNSW parameters not tuned).
20
+
21
+ **Step 3 — Emit hybrid search**
22
+ Emit: combined BM25 + vector search with reciprocal rank fusion, similarity threshold filtering, query embedding cache, and HNSW index tuning.
23
+
24
+ #### Example
25
+
26
+ ```typescript
27
+ // Hybrid search — BM25 + vector with reciprocal rank fusion
28
+ async function hybridSearch(query: string, limit = 10) {
29
+ // Parallel: keyword (BM25) + semantic (vector)
30
+ const [keywordResults, vectorResults] = await Promise.all([
31
+ db.execute(sql`
32
+ SELECT id, content, ts_rank(search_vector, plainto_tsquery(${query})) AS bm25_score
33
+ FROM documents
34
+ WHERE search_vector @@ plainto_tsquery(${query})
35
+ ORDER BY bm25_score DESC LIMIT ${limit * 2}
36
+ `),
37
+ db.execute(sql`
38
+ SELECT id, content, 1 - (embedding <=> ${await getEmbedding(query)}) AS vector_score
39
+ FROM documents
40
+ ORDER BY embedding <=> ${await getEmbedding(query)}
41
+ LIMIT ${limit * 2}
42
+ `),
43
+ ]);
44
+
45
+ // Reciprocal rank fusion (k=60)
46
+ const scores = new Map<string, number>();
47
+ const K = 60;
48
+ keywordResults.forEach((r, i) => scores.set(r.id, (scores.get(r.id) || 0) + 1 / (K + i + 1)));
49
+ vectorResults.forEach((r, i) => scores.set(r.id, (scores.get(r.id) || 0) + 1 / (K + i + 1)));
50
+
51
+ return [...scores.entries()]
52
+ .sort((a, b) => b[1] - a[1])
53
+ .slice(0, limit)
54
+ .filter(([_, score]) => score > 0.01); // threshold
55
+ }
56
+
57
+ // Embedding cache (avoid re-embedding repeated queries)
58
+ const embeddingCache = new Map<string, number[]>();
59
+ async function getEmbedding(text: string): Promise<number[]> {
60
+ const cached = embeddingCache.get(text);
61
+ if (cached) return cached;
62
+ const { data } = await openai.embeddings.create({ model: 'text-embedding-3-small', input: text });
63
+ embeddingCache.set(text, data[0].embedding);
64
+ return data[0].embedding;
65
+ }
66
+ ```
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: "fine-tuning-guide"
3
+ pack: "@rune/ai-ml"
4
+ description: "Fine-tuning workflows — dataset preparation, training configuration, evaluation metrics, deployment, A/B testing."
5
+ model: sonnet
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ ---
8
+
9
+ # fine-tuning-guide
10
+
11
+ Fine-tuning workflows — dataset preparation, training configuration, evaluation metrics, deployment, A/B testing.
12
+
13
+ #### Workflow
14
+
15
+ **Step 1 — Audit training data**
16
+ Use Read to examine the dataset files. Check for: data format (JSONL with `messages` array), train/eval split (eval must not overlap with train), sufficient examples (minimum 50, recommended 200+), balanced class distribution, and PII in training data.
17
+
18
+ **Step 2 — Prepare and validate dataset**
19
+ Emit: JSONL formatter that validates each example, train/eval splitter with stratification, token count estimator (cost preview), and data quality checks (duplicate detection, format validation).
20
+
21
+ **Step 3 — Execute fine-tuning and evaluate**
22
+ Emit: fine-tune API call with hyperparameters, evaluation script that compares base vs fine-tuned on held-out set, and A/B deployment configuration.
23
+
24
+ #### Example
25
+
26
+ ```python
27
+ # Fine-tuning workflow — prepare, train, evaluate
28
+ import json
29
+ import openai
30
+ from sklearn.model_selection import train_test_split
31
+
32
+ # Step 1: Prepare JSONL dataset
33
+ def prepare_dataset(examples: list[dict], output_prefix: str):
34
+ train, eval_set = train_test_split(examples, test_size=0.2, random_state=42)
35
+
36
+ for split_name, split_data in [("train", train), ("eval", eval_set)]:
37
+ path = f"{output_prefix}_{split_name}.jsonl"
38
+ with open(path, "w") as f:
39
+ for ex in split_data:
40
+ f.write(json.dumps({"messages": [
41
+ {"role": "system", "content": ex["system"]},
42
+ {"role": "user", "content": ex["input"]},
43
+ {"role": "assistant", "content": ex["output"]},
44
+ ]}) + "\n")
45
+ print(f"Wrote {len(split_data)} examples to {path}")
46
+
47
+ # Step 2: Launch fine-tuning
48
+ def start_fine_tune(train_file: str, eval_file: str):
49
+ train_id = openai.files.create(file=open(train_file, "rb"), purpose="fine-tune").id
50
+ eval_id = openai.files.create(file=open(eval_file, "rb"), purpose="fine-tune").id
51
+
52
+ job = openai.fine_tuning.jobs.create(
53
+ training_file=train_id,
54
+ validation_file=eval_id,
55
+ model="gpt-4o-mini-2024-07-18",
56
+ hyperparameters={"n_epochs": 3, "batch_size": "auto", "learning_rate_multiplier": "auto"},
57
+ )
58
+ print(f"Fine-tuning job: {job.id} — status: {job.status}")
59
+ return job
60
+
61
+ # Step 3: Evaluate base vs fine-tuned
62
+ def evaluate(base_model: str, ft_model: str, eval_set: list[dict]) -> dict:
63
+ results = {"base": {"correct": 0}, "finetuned": {"correct": 0}}
64
+ for ex in eval_set:
65
+ for label, model in [("base", base_model), ("finetuned", ft_model)]:
66
+ response = openai.chat.completions.create(
67
+ model=model, messages=ex["messages"][:2], max_tokens=500,
68
+ )
69
+ if response.choices[0].message.content.strip() == ex["messages"][2]["content"].strip():
70
+ results[label]["correct"] += 1
71
+ for label in results:
72
+ results[label]["accuracy"] = results[label]["correct"] / len(eval_set)
73
+ return results
74
+ ```