@rune-kit/rune 2.2.0 → 2.2.1
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.
- package/README.md +40 -34
- package/compiler/__tests__/pack-split.test.js +145 -0
- package/compiler/bin/rune.js +0 -5
- package/compiler/doctor.js +42 -0
- package/compiler/emitter.js +27 -4
- package/compiler/parser.js +41 -3
- package/compiler/transformer.js +10 -6
- package/compiler/transforms/compliance.js +40 -0
- package/extensions/ai-ml/PACK.md +38 -474
- package/extensions/ai-ml/skills/ai-agents.md +172 -0
- package/extensions/ai-ml/skills/code-sandbox.md +187 -0
- package/extensions/ai-ml/skills/deep-research.md +146 -0
- package/extensions/ai-ml/skills/embedding-search.md +66 -0
- package/extensions/ai-ml/skills/fine-tuning-guide.md +74 -0
- package/extensions/ai-ml/skills/llm-architect.md +125 -0
- package/extensions/ai-ml/skills/llm-integration.md +64 -0
- package/extensions/ai-ml/skills/prompt-patterns.md +72 -0
- package/extensions/ai-ml/skills/rag-patterns.md +66 -0
- package/extensions/ai-ml/skills/web-extraction.md +114 -0
- package/extensions/analytics/PACK.md +19 -484
- package/extensions/analytics/skills/ab-testing.md +72 -0
- package/extensions/analytics/skills/dashboard-patterns.md +83 -0
- package/extensions/analytics/skills/data-validation.md +68 -0
- package/extensions/analytics/skills/funnel-analysis.md +81 -0
- package/extensions/analytics/skills/sql-patterns.md +57 -0
- package/extensions/analytics/skills/statistical-analysis.md +79 -0
- package/extensions/analytics/skills/tracking-setup.md +71 -0
- package/extensions/backend/PACK.md +44 -618
- package/extensions/backend/skills/api-patterns.md +84 -0
- package/extensions/backend/skills/async-pipeline.md +193 -0
- package/extensions/backend/skills/auth-patterns.md +97 -0
- package/extensions/backend/skills/background-jobs.md +133 -0
- package/extensions/backend/skills/caching-patterns.md +108 -0
- package/extensions/backend/skills/cli-generation.md +133 -0
- package/extensions/backend/skills/database-patterns.md +87 -0
- package/extensions/backend/skills/middleware-patterns.md +104 -0
- package/extensions/chrome-ext/PACK.md +19 -921
- package/extensions/chrome-ext/skills/cws-preflight.md +143 -0
- package/extensions/chrome-ext/skills/cws-publish.md +104 -0
- package/extensions/chrome-ext/skills/ext-ai-integration.md +251 -0
- package/extensions/chrome-ext/skills/ext-messaging.md +139 -0
- package/extensions/chrome-ext/skills/ext-storage.md +133 -0
- package/extensions/chrome-ext/skills/mv3-scaffold.md +164 -0
- package/extensions/content/PACK.md +43 -335
- package/extensions/content/skills/blog-patterns.md +88 -0
- package/extensions/content/skills/cms-integration.md +131 -0
- package/extensions/content/skills/content-scoring.md +107 -0
- package/extensions/content/skills/i18n.md +83 -0
- package/extensions/content/skills/mdx-authoring.md +137 -0
- package/extensions/content/skills/reference.md +1014 -0
- package/extensions/content/skills/seo-patterns.md +67 -0
- package/extensions/content/skills/video-repurpose.md +153 -0
- package/extensions/devops/PACK.md +38 -457
- package/extensions/devops/skills/chaos-testing.md +67 -0
- package/extensions/devops/skills/ci-cd.md +75 -0
- package/extensions/devops/skills/docker.md +58 -0
- package/extensions/devops/skills/edge-serverless.md +163 -0
- package/extensions/devops/skills/infra-as-code.md +158 -0
- package/extensions/devops/skills/kubernetes.md +110 -0
- package/extensions/devops/skills/monitoring.md +57 -0
- package/extensions/devops/skills/server-setup.md +64 -0
- package/extensions/devops/skills/ssl-domain.md +42 -0
- package/extensions/ecommerce/PACK.md +62 -226
- package/extensions/ecommerce/skills/cart-system.md +79 -0
- package/extensions/ecommerce/skills/inventory-mgmt.md +102 -0
- package/extensions/ecommerce/skills/order-management.md +126 -0
- package/extensions/ecommerce/skills/payment-integration.md +472 -0
- package/extensions/ecommerce/skills/shopify-dev.md +69 -0
- package/extensions/ecommerce/skills/subscription-billing.md +93 -0
- package/extensions/ecommerce/skills/tax-compliance.md +117 -0
- package/extensions/gamedev/PACK.md +66 -317
- package/extensions/gamedev/skills/asset-pipeline.md +74 -0
- package/extensions/gamedev/skills/audio-system.md +129 -0
- package/extensions/gamedev/skills/camera-system.md +87 -0
- package/extensions/gamedev/skills/ecs.md +98 -0
- package/extensions/gamedev/skills/game-loops.md +72 -0
- package/extensions/gamedev/skills/input-system.md +199 -0
- package/extensions/gamedev/skills/multiplayer.md +180 -0
- package/extensions/gamedev/skills/particles.md +105 -0
- package/extensions/gamedev/skills/physics-engine.md +89 -0
- package/extensions/gamedev/skills/scene-management.md +146 -0
- package/extensions/gamedev/skills/threejs-patterns.md +90 -0
- package/extensions/gamedev/skills/webgl.md +71 -0
- package/extensions/mobile/PACK.md +56 -223
- package/extensions/mobile/skills/app-store-connect.md +152 -0
- package/extensions/mobile/skills/app-store-prep.md +66 -0
- package/extensions/mobile/skills/deep-linking.md +109 -0
- package/extensions/mobile/skills/flutter.md +60 -0
- package/extensions/mobile/skills/ios-build-pipeline.md +142 -0
- package/extensions/mobile/skills/native-bridge.md +66 -0
- package/extensions/mobile/skills/ota-updates.md +97 -0
- package/extensions/mobile/skills/push-notifications.md +111 -0
- package/extensions/mobile/skills/react-native.md +82 -0
- package/extensions/saas/PACK.md +26 -720
- package/extensions/saas/skills/billing-integration.md +121 -0
- package/extensions/saas/skills/feature-flags.md +130 -0
- package/extensions/saas/skills/multi-tenant.md +103 -0
- package/extensions/saas/skills/onboarding-flow.md +139 -0
- package/extensions/saas/skills/subscription-flow.md +95 -0
- package/extensions/saas/skills/team-management.md +144 -0
- package/extensions/security/PACK.md +10 -448
- package/extensions/security/skills/api-security.md +140 -0
- package/extensions/security/skills/compliance.md +68 -0
- package/extensions/security/skills/owasp-audit.md +64 -0
- package/extensions/security/skills/pentest-patterns.md +77 -0
- package/extensions/security/skills/secret-mgmt.md +65 -0
- package/extensions/security/skills/supply-chain.md +65 -0
- package/extensions/trading/PACK.md +18 -535
- package/extensions/trading/skills/chart-components.md +55 -0
- package/extensions/trading/skills/experiment-loop.md +125 -0
- package/extensions/trading/skills/fintech-patterns.md +47 -0
- package/extensions/trading/skills/indicator-library.md +58 -0
- package/extensions/trading/skills/quant-analysis.md +111 -0
- package/extensions/trading/skills/realtime-data.md +58 -0
- package/extensions/trading/skills/trade-logic.md +104 -0
- package/extensions/ui/PACK.md +34 -853
- package/extensions/ui/skills/a11y-audit.md +91 -0
- package/extensions/ui/skills/animation-patterns.md +106 -0
- package/extensions/ui/skills/component-patterns.md +75 -0
- package/extensions/ui/skills/design-decision.md +98 -0
- package/extensions/ui/skills/design-system.md +68 -0
- package/extensions/ui/skills/landing-patterns.md +155 -0
- package/extensions/ui/skills/palette-picker.md +162 -0
- package/extensions/ui/skills/react-health.md +90 -0
- package/extensions/ui/skills/type-system.md +125 -0
- package/extensions/ui/skills/web-vitals.md +153 -0
- package/extensions/zalo/PACK.md +117 -0
- package/extensions/zalo/skills/zalo-oa-mcp.md +317 -0
- package/extensions/zalo/skills/zalo-oa-messaging.md +429 -0
- package/extensions/zalo/skills/zalo-oa-setup.md +236 -0
- package/extensions/zalo/skills/zalo-oa-webhook.md +189 -0
- package/extensions/zalo/skills/zalo-personal-messaging.md +194 -0
- package/extensions/zalo/skills/zalo-personal-setup.md +153 -0
- package/extensions/zalo/skills/zalo-rate-guard.md +219 -0
- package/package.json +1 -1
- package/skills/brainstorm/SKILL.md +63 -1
- package/skills/cook/SKILL.md +84 -5
- package/skills/mcp-builder/SKILL.md +48 -1
- package/skills/review/SKILL.md +42 -5
- package/skills/review-intake/SKILL.md +17 -1
- package/skills/skill-router/SKILL.md +89 -7
- package/skills/team/SKILL.md +24 -1
- package/skills/test/SKILL.md +18 -0
- package/skills/verification/SKILL.md +40 -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
|
+
```
|