@bolloon/bolloon-agent 0.3.29 → 0.3.31

package/dist/agents/pi-sdk-tools.js

@@ -948,6 +948,134 @@ export function registerBuiltinTools(ctx) {
             }
         }
     });
+    // ============================================================
+    // Web 上网工具 (2026-08-04) — fetch_url + web_search
+    // 用 undici request (独立连接池, 与 pi-ai 一致, 避开全局 fetch 僵尸连接问题)
+    // ============================================================
+    ctx.tools.set('fetch_url', {
+        name: 'fetch_url',
+        description: '抓取一个 URL 的网页内容并转成纯文本. 适合查文档/新闻/API 页面. 返回前 4000 字符. HTML 自动去标签, JSON/文本原样返回. (走 curl, 兼容 TLS 指纹风控)',
+        parameters: { url: '完整 URL (必填, 含 https://)' },
+        execute: async (args) => {
+            try {
+                const url = String(args.url || '').trim();
+                if (!url)
+                    return { success: false, error: 'url 必填' };
+                if (!/^https?:\/\//i.test(url))
+                    return { success: false, error: 'url 必须以 http(s):// 开头' };
+                const { execFile } = await import('child_process');
+                const { promisify } = await import('util');
+                const pExecFile = promisify(execFile);
+                const { stdout, stderr } = await pExecFile('curl', [
+                    '-sL', '--max-time', '25',
+                    '-A', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36',
+                    '-H', 'Accept-Language: zh-CN,zh;q=0.9,en;q=0.8',
+                    url,
+                ], { maxBuffer: 2 * 1024 * 1024, timeout: 30_000 });
+                if (!stdout && stderr)
+                    return { success: false, error: `fetch_url 失败: ${String(stderr).slice(0, 200)}` };
+                const raw = stdout.slice(0, 60_000);
+                const trimmed = raw.trimStart();
+                let text;
+                if (trimmed.startsWith('<!doctype') || trimmed.startsWith('<html') || /^<\?xml/i.test(trimmed)) {
+                    text = raw
+                        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+                        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+                        .replace(/<[^>]+>/g, ' ')
+                        .replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+                        .replace(/\s+/g, ' ')
+                        .trim();
+                }
+                else {
+                    text = raw;
+                }
+                const out = text.slice(0, 4000);
+                return { success: true, output: `🌐 ${url} (${raw.length} bytes):\n${out}${text.length > 4000 ? '\n...(截断, 共 ' + text.length + ' 字符)' : ''}` };
+            }
+            catch (e) {
+                return { success: false, error: `fetch_url 失败: ${String(e?.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('web_search', {
+        name: 'web_search',
+        description: '网页搜索. 无 key 时走 DuckDuckGo Instant Answer API + Wikipedia (知识/资讯查询可靠); 配置 TAVILY_API_KEY 时走 Tavily 完整搜索 (更全). 返回前 8 条标题+URL+摘要.',
+        parameters: { query: '搜索词 (必填)' },
+        execute: async (args) => {
+            try {
+                const query = String(args.query || '').trim();
+                if (!query)
+                    return { success: false, error: 'query 必填' };
+                const { execFile } = await import('child_process');
+                const { promisify } = await import('util');
+                const pExecFile = promisify(execFile);
+                const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36';
+                const curlJson = async (url) => {
+                    const r = await pExecFile('curl', ['-s', '--max-time', '15', '-A', UA, url], { maxBuffer: 4 * 1024 * 1024, timeout: 20_000 });
+                    return JSON.parse(r.stdout);
+                };
+                // 引擎 0: Tavily (配了 TAVILY_API_KEY 时最完整)
+                const tavilyKey = process.env.TAVILY_API_KEY || '';
+                if (tavilyKey) {
+                    const r = await pExecFile('curl', [
+                        '-s', '--max-time', '20', '-A', UA,
+                        '-X', 'POST', 'https://api.tavily.com/search',
+                        '-H', 'Content-Type: application/json',
+                        '-d', JSON.stringify({ api_key: tavilyKey, query, max_results: 8, include_answer: true }),
+                    ], { maxBuffer: 4 * 1024 * 1024, timeout: 25_000 });
+                    const d = JSON.parse(r.stdout);
+                    const results = d.results || [];
+                    if (results.length > 0) {
+                        const lines = results.slice(0, 8).map((x, i) => `${i + 1}. ${x.title}\n  ${x.url}${x.content ? '\n   ' + String(x.content).replace(/\s+/g, ' ').slice(0, 150) : ''}`);
+                        const answer = d.answer ? `\n📌 ${d.answer}\n` : '';
+                        return { success: true, output: `🔎 "${query}" 结果 ${results.length} 条 (Tavily):${answer}\n\n${lines.join('\n\n')}` };
+                    }
+                }
+                // 引擎 1: DuckDuckGo Instant Answer API (摘要 + 相关主题)
+                try {
+                    const ia = await curlJson(`https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_html=1`);
+                    const out = [];
+                    if (ia.AbstractText && ia.AbstractURL) {
+                        out.push(`📖 ${ia.AbstractText.slice(0, 400)}\n  ${ia.AbstractURL}`);
+                    }
+                    const topics = Array.isArray(ia.RelatedTopics) ? ia.RelatedTopics : [];
+                    for (const t of topics) {
+                        if (out.length >= 8)
+                            break;
+                        if (t.Topics) { // 分类组
+                            for (const sub of t.Topics) {
+                                if (out.length >= 8)
+                                    break;
+                                if (sub.Text && sub.FirstURL)
+                                    out.push(`${out.length + 1}. ${sub.Text.slice(0, 200)}\n  ${sub.FirstURL}`);
+                            }
+                        }
+                        else if (t.Text && t.FirstURL) {
+                            out.push(`${out.length + 1}. ${t.Text.slice(0, 200)}\n  ${t.FirstURL}`);
+                        }
+                    }
+                    if (out.length > 0) {
+                        return { success: true, output: `🔎 "${query}" (DuckDuckGo):\n\n${out.join('\n\n')}` };
+                    }
+                }
+                catch { /* fallback */ }
+                // 引擎 2: Wikipedia 搜索 API
+                try {
+                    const wiki = await curlJson(`https://zh.wikipedia.org/w/api.php?action=query&list=search&srsearch=${encodeURIComponent(query)}&format=json&srlimit=5`);
+                    const hits = wiki?.query?.search || [];
+                    if (hits.length > 0) {
+                        const lines = hits.map((h, i) => `${i + 1}. ${h.title}\n  https://zh.wikipedia.org/wiki/${encodeURIComponent(h.title.replace(/ /g, '_'))}\n   ${String(h.snippet || '').replace(/<[^>]+>/g, '').slice(0, 120)}`);
+                        return { success: true, output: `🔎 "${query}" (维基百科 ${hits.length} 条):\n\n${lines.join('\n\n')}` };
+                    }
+                }
+                catch { /* fallback */ }
+                return { success: true, output: `🔎 "${query}" 无结果 (免费引擎无匹配, 可配 TAVILY_API_KEY 提升覆盖)` };
+            }
+            catch (e) {
+                return { success: false, error: `web_search 失败: ${String(e?.message || e).slice(0, 200)}` };
+            }
+        }
+    });
     ctx.tools.set('git_log', {
         name: 'git_log',
         description: '查看 git log. 默认 --oneline -10. 支持过滤和范围.',

package/dist/constraint-runtime/_archive_helper.d.ts

@@ -0,0 +1 @@
+export declare function loadArchiveMetadata(packageName: string): Record<string, unknown>;

package/dist/constraint-runtime/_archive_helper.js

@@ -0,0 +1,9 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export function loadArchiveMetadata(packageName) {
+    const snapshotPath = path.join(__dirname, 'reference_data', 'subsystems', `${packageName}.json`);
+    return JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
+}

package/dist/constraint-runtime/agent/coordinator.d.ts

@@ -0,0 +1,19 @@
+export interface SubTask {
+    id: string;
+    description: string;
+    priority: number;
+}
+export interface AgentResult {
+    taskId: string;
+    output: string;
+    success: boolean;
+    metadata?: Record<string, unknown>;
+}
+export declare class AgentCoordinator {
+    private engine;
+    constructor(maxDepth?: number);
+    dispatch(prompt: string, parallelCount?: number): Promise<AgentResult[]>;
+    private splitTask;
+    private executeTask;
+    private aggregate;
+}

package/dist/constraint-runtime/agent/coordinator.js

@@ -0,0 +1,48 @@
+import { DeepThinkingEngine } from '../thinking/engine.js';
+export class AgentCoordinator {
+    engine;
+    constructor(maxDepth = 3) {
+        this.engine = new DeepThinkingEngine(maxDepth);
+    }
+    async dispatch(prompt, parallelCount = 3) {
+        const tasks = this.splitTask(prompt, parallelCount);
+        const results = await Promise.all(tasks.map(task => this.executeTask(task)));
+        return this.aggregate(results);
+    }
+    splitTask(prompt, count) {
+        const words = prompt.split(/\s+/);
+        const chunkSize = Math.ceil(words.length / count);
+        const chunks = [];
+        for (let i = 0; i < count; i++) {
+            const chunk = words.slice(i * chunkSize, (i + 1) * chunkSize).join(' ');
+            if (chunk) {
+                chunks.push({
+                    id: `task-${i}`,
+                    description: chunk,
+                    priority: i
+                });
+            }
+        }
+        return chunks;
+    }
+    async executeTask(task) {
+        try {
+            const thinkResult = await this.engine.think(task.description);
+            return {
+                taskId: task.id,
+                output: thinkResult.finalOutput,
+                success: true
+            };
+        }
+        catch (error) {
+            return {
+                taskId: task.id,
+                output: String(error),
+                success: false
+            };
+        }
+    }
+    aggregate(results) {
+        return results.sort((a, b) => a.taskId.localeCompare(b.taskId));
+    }
+}

package/dist/constraint-runtime/agent/index.d.ts

@@ -0,0 +1 @@
+export { AgentCoordinator, type SubTask, type AgentResult } from './coordinator.js';

package/dist/constraint-runtime/agent/index.js

@@ -0,0 +1 @@
+export { AgentCoordinator } from './coordinator.js';

package/dist/constraint-runtime/assistant/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/assistant/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('assistant');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/bootstrap/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/bootstrap/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('bootstrap');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/bootstrap_graph.d.ts

@@ -0,0 +1,4 @@
+export interface BootstrapGraph {
+    stages: string[];
+}
+export declare function buildBootstrapGraph(): BootstrapGraph;

package/dist/constraint-runtime/bootstrap_graph.js

@@ -0,0 +1,13 @@
+export function buildBootstrapGraph() {
+    return {
+        stages: [
+            'top-level prefetch side effects',
+            'warning handler and environment guards',
+            'CLI parser and pre-action trust gate',
+            'setup() + commands/agents parallel load',
+            'deferred init after trust',
+            'mode routing: local / remote / ssh / teleport / direct-connect / deep-link',
+            'query engine submit loop',
+        ],
+    };
+}

package/dist/constraint-runtime/bridge/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/bridge/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('bridge');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/buddy/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/buddy/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('buddy');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/cli/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/cli/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('cli');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/command_graph.d.ts

@@ -0,0 +1,7 @@
+import { PortingModule } from './models.js';
+export interface CommandGraph {
+    builtins: PortingModule[];
+    pluginLike: PortingModule[];
+    skillLike: PortingModule[];
+}
+export declare function buildCommandGraph(): CommandGraph;

package/dist/constraint-runtime/command_graph.js

@@ -0,0 +1,10 @@
+import { getCommands } from './commands.js';
+export function buildCommandGraph() {
+    const commands = getCommands();
+    return {
+        builtins: commands.filter(m => !m.sourceHint.toLowerCase().includes('plugin') &&
+            !m.sourceHint.toLowerCase().includes('skills')),
+        pluginLike: commands.filter(m => m.sourceHint.toLowerCase().includes('plugin')),
+        skillLike: commands.filter(m => m.sourceHint.toLowerCase().includes('skills')),
+    };
+}

package/dist/constraint-runtime/commands.d.ts

@@ -0,0 +1,15 @@
+import { PortingModule } from './models.js';
+export interface CommandExecution {
+    name: string;
+    sourceHint: string;
+    prompt: string;
+    handled: boolean;
+    message: string;
+}
+export declare const PORTED_COMMANDS: PortingModule[];
+export { PortingModule };
+export declare function builtInCommandNames(): Set<string>;
+export declare function getCommand(name: string): PortingModule | undefined;
+export declare function getCommands(includePluginCommands?: boolean, includeSkillCommands?: boolean): PortingModule[];
+export declare function findCommands(query: string, limit?: number): PortingModule[];
+export declare function executeCommand(name: string, prompt?: string): CommandExecution;

package/dist/constraint-runtime/commands.js

@@ -0,0 +1,60 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SNAPSHOT_PATH = path.join(__dirname, 'reference_data', 'commands_snapshot.json');
+function loadCommandSnapshot() {
+    try {
+        if (!fs.existsSync(SNAPSHOT_PATH)) {
+            console.warn(`[commands] Snapshot not found: ${SNAPSHOT_PATH}, using empty list`);
+            return [];
+        }
+        const raw = JSON.parse(fs.readFileSync(SNAPSHOT_PATH, 'utf-8'));
+        return raw.map((e) => ({
+            name: e.name,
+            responsibility: e.responsibility,
+            sourceHint: e.source_hint,
+            status: 'mirrored',
+        }));
+    }
+    catch (error) {
+        console.warn(`[commands] Failed to load snapshot: ${error}, using empty list`);
+        return [];
+    }
+}
+export const PORTED_COMMANDS = loadCommandSnapshot();
+export function builtInCommandNames() {
+    return new Set(PORTED_COMMANDS.map(m => m.name));
+}
+export function getCommand(name) {
+    const needle = name.toLowerCase();
+    return PORTED_COMMANDS.find(m => m.name.toLowerCase() === needle);
+}
+export function getCommands(includePluginCommands = true, includeSkillCommands = true) {
+    let commands = [...PORTED_COMMANDS];
+    if (!includePluginCommands) {
+        commands = commands.filter(m => !m.sourceHint.toLowerCase().includes('plugin'));
+    }
+    if (!includeSkillCommands) {
+        commands = commands.filter(m => !m.sourceHint.toLowerCase().includes('skills'));
+    }
+    return commands;
+}
+export function findCommands(query, limit = 20) {
+    const needle = query.toLowerCase();
+    return PORTED_COMMANDS.filter(m => m.name.toLowerCase().includes(needle) || m.sourceHint.toLowerCase().includes(needle)).slice(0, limit);
+}
+export function executeCommand(name, prompt = '') {
+    const module = getCommand(name);
+    if (!module) {
+        return { name, sourceHint: '', prompt, handled: false, message: `Unknown mirrored command: ${name}` };
+    }
+    return {
+        name: module.name,
+        sourceHint: module.sourceHint,
+        prompt,
+        handled: true,
+        message: `Mirrored command '${module.name}' from ${module.sourceHint} would handle prompt.`,
+    };
+}

package/dist/constraint-runtime/components/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/components/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('components');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/constants/index.d.ts

@@ -0,0 +1,11 @@
+export declare const ARCHIVE_NAME: string;
+export declare const MODULE_COUNT: number;
+export declare const SAMPLE_FILES: string[];
+export declare const PORTING_NOTE: string;
+declare const _default: {
+    ARCHIVE_NAME: string;
+    MODULE_COUNT: number;
+    PORTING_NOTE: string;
+    SAMPLE_FILES: string[];
+};
+export default _default;

package/dist/constraint-runtime/constants/index.js

@@ -0,0 +1,12 @@
+import { loadArchiveMetadata } from '../_archive_helper.js';
+const SNAPSHOT = loadArchiveMetadata('constants');
+export const ARCHIVE_NAME = SNAPSHOT['archive_name'];
+export const MODULE_COUNT = SNAPSHOT['module_count'];
+export const SAMPLE_FILES = SNAPSHOT['sample_files'];
+export const PORTING_NOTE = `Python placeholder package for '${ARCHIVE_NAME}' with ${MODULE_COUNT} archived module references.`;
+export default {
+    ARCHIVE_NAME,
+    MODULE_COUNT,
+    PORTING_NOTE,
+    SAMPLE_FILES,
+};

package/dist/constraint-runtime/constraint/budget.d.ts

@@ -0,0 +1,11 @@
+import { UsageSummary } from '../models.js';
+export declare class BudgetTracker {
+    maxBudgetTokens: number;
+    maxTurns: number;
+    compactAfterTurns: number;
+    constructor(maxBudgetTokens?: number, maxTurns?: number, compactAfterTurns?: number);
+    addTurn(inputTokens: number, outputTokens: number): UsageSummary;
+    isBudgetExceeded(usage: UsageSummary): boolean;
+    isTurnLimitExceeded(currentTurns: number): boolean;
+    shouldCompact(turnCount: number): boolean;
+}

package/dist/constraint-runtime/constraint/budget.js

@@ -0,0 +1,22 @@
+export class BudgetTracker {
+    maxBudgetTokens;
+    maxTurns;
+    compactAfterTurns;
+    constructor(maxBudgetTokens = 2000, maxTurns = 8, compactAfterTurns = 12) {
+        this.maxBudgetTokens = maxBudgetTokens;
+        this.maxTurns = maxTurns;
+        this.compactAfterTurns = compactAfterTurns;
+    }
+    addTurn(inputTokens, outputTokens) {
+        return { inputTokens, outputTokens };
+    }
+    isBudgetExceeded(usage) {
+        return usage.inputTokens + usage.outputTokens > this.maxBudgetTokens;
+    }
+    isTurnLimitExceeded(currentTurns) {
+        return currentTurns >= this.maxTurns;
+    }
+    shouldCompact(turnCount) {
+        return turnCount > this.compactAfterTurns;
+    }
+}

package/dist/constraint-runtime/constraint/index.d.ts

@@ -0,0 +1,3 @@
+export { ToolPermissionContext } from './permission.js';
+export { BudgetTracker } from './budget.js';
+export type { UsageSummary } from '../models.js';

package/dist/constraint-runtime/constraint/index.js

@@ -0,0 +1,2 @@
+export { ToolPermissionContext } from './permission.js';
+export { BudgetTracker } from './budget.js';

package/dist/constraint-runtime/constraint/permission.d.ts

@@ -0,0 +1,9 @@
+import { PermissionDenial } from '../models.js';
+export declare class ToolPermissionContext {
+    private denyTools;
+    private denyPrefixes;
+    private constructor();
+    static fromIterables(denyTools?: string[], denyPrefixes?: string[]): ToolPermissionContext;
+    blocks(name: string): boolean;
+    createDenial(toolName: string, reason: string): PermissionDenial;
+}

package/dist/constraint-runtime/constraint/permission.js

@@ -0,0 +1,20 @@
+export class ToolPermissionContext {
+    denyTools;
+    denyPrefixes;
+    constructor(denyTools, denyPrefixes) {
+        this.denyTools = denyTools;
+        this.denyPrefixes = denyPrefixes;
+    }
+    static fromIterables(denyTools = [], denyPrefixes = []) {
+        return new ToolPermissionContext(new Set(denyTools.map(t => t.toLowerCase())), denyPrefixes);
+    }
+    blocks(name) {
+        const lower = name.toLowerCase();
+        if (this.denyTools.has(lower))
+            return true;
+        return this.denyPrefixes.some(p => lower.startsWith(p.toLowerCase()));
+    }
+    createDenial(toolName, reason) {
+        return { toolName, reason };
+    }
+}

package/dist/constraint-runtime/context.d.ts

@@ -0,0 +1,12 @@
+export interface PortContext {
+    sourceRoot: string;
+    testsRoot: string;
+    assetsRoot: string;
+    archiveRoot: string;
+    pythonFileCount: number;
+    testFileCount: number;
+    assetFileCount: number;
+    archiveAvailable: boolean;
+}
+export declare function buildPortContext(base?: string): PortContext;
+export declare function renderContext(context: PortContext): string;

package/dist/constraint-runtime/context.js

@@ -0,0 +1,30 @@
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export function buildPortContext(base) {
+    const root = base || __dirname;
+    const srcRoot = path.join(root, 'src');
+    const testsRoot = path.join(root, 'tests');
+    const assetsRoot = path.join(root, 'assets');
+    const archiveRoot = path.join(root, 'archive');
+    return {
+        sourceRoot: srcRoot,
+        testsRoot: testsRoot,
+        assetsRoot: assetsRoot,
+        archiveRoot: archiveRoot,
+        pythonFileCount: 0,
+        testFileCount: 0,
+        assetFileCount: 0,
+        archiveAvailable: false,
+    };
+}
+export function renderContext(context) {
+    return [
+        `Source root: ${context.sourceRoot}`,
+        `Test root: ${context.testsRoot}`,
+        `Assets root: ${context.assetsRoot}`,
+        `Archive root: ${context.archiveRoot}`,
+        `Archive available: ${context.archiveAvailable}`,
+    ].join('\n');
+}