qaify-playwright-reporter 0.9.5 → 0.10.0

package/dist/agent/command.d.ts

@@ -0,0 +1,19 @@
+import { type AgentOutput } from './run.js';
+export interface AgentCommandOptions {
+    envFile: string;
+    out: string;
+    schemaFile: string;
+    promptFile?: string;
+    prompt?: string;
+    inputFile?: string;
+    instructionsFile?: string;
+    tools: string[];
+    maxTurns: number;
+    mcpConfig?: string;
+    model?: string;
+    cwd: string;
+    log?: (msg: string) => void;
+    fetch?: typeof fetch;
+}
+export declare function childEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function agentCommand(options: AgentCommandOptions): Promise<AgentOutput>;

package/dist/agent/command.js

@@ -0,0 +1,76 @@
+// `qaify agent`: jalankan Qaify Agent dengan kredensial dari env file `qaify ai-env`, tulis claude.json.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { consumeEnvFile, MODEL_PATTERN } from '../ai-env.js';
+import { loadMcpConfig, McpServer } from './mcp.js';
+import { runAgent } from './run.js';
+/** Variabel yang tidak boleh diwarisi bash / server MCP (key AI, token Qaify, token langganan). */
+const PRIVATE_ENV = /^(QAIFY_AI_|ANTHROPIC_|QA_FACTORY_TOKEN$|CLAUDE_CODE_OAUTH_TOKEN$|GITHUB_TOKEN$|ACTIONS_RUNTIME_TOKEN$|ACTIONS_ID_TOKEN_REQUEST_)/;
+export function childEnv(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([name]) => !PRIVATE_ENV.test(name)));
+}
+export async function agentCommand(options) {
+    const log = options.log ?? console.log;
+    const env = await consumeEnvFile(options.envFile);
+    const model = options.model && MODEL_PATTERN.test(options.model) ? options.model : env.QAIFY_AI_MODEL;
+    const write = async (output) => {
+        await mkdir(dirname(options.out), { recursive: true });
+        await writeFile(options.out, JSON.stringify(output));
+        return output;
+    };
+    const fail = (message, code) => write({
+        type: 'result', subtype: `error_${code}`, is_error: true, result: message, num_turns: 0, duration_ms: 0, total_cost_usd: null,
+        usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0 }, modelUsage: {}, engine: 'qaify_agent',
+        provider: env.QAIFY_AI_PROVIDER ?? 'unknown', error_code: code,
+    });
+    if (!env.QAIFY_AI_API_KEY || !env.QAIFY_AI_BASE_URL || !model) {
+        log('::error::Qaify Agent: API key / base URL / model tidak tersedia (step "Pilih agen AI" gagal?)');
+        return fail('API key Qaify Agent tidak tersedia di runner.', 'ai_env_missing');
+    }
+    const schema = JSON.parse(await readFile(options.schemaFile, 'utf8'));
+    const instructions = options.instructionsFile ? await readFile(options.instructionsFile, 'utf8') : '';
+    let prompt = options.promptFile ? await readFile(options.promptFile, 'utf8') : (options.prompt ?? '');
+    if (options.inputFile)
+        prompt += `\n\nInput JSON:\n\`\`\`json\n${await readFile(options.inputFile, 'utf8')}\n\`\`\``;
+    const safeEnv = childEnv();
+    const servers = [];
+    if (options.mcpConfig) {
+        for (const [name, config] of Object.entries(await loadMcpConfig(options.mcpConfig))) {
+            const server = new McpServer(name, config, safeEnv, (m) => log(m.slice(0, 500)));
+            try {
+                await server.start();
+                servers.push(server);
+                log(`qaify-agent: server MCP ${name} siap (${server.tools.length} tool)`);
+            }
+            catch (e) {
+                server.close();
+                log(`::warning::Server MCP ${name} gagal dijalankan (${e.message}); agen berjalan tanpa tool itu.`);
+            }
+        }
+    }
+    const price = (name) => (env[name] !== undefined && env[name] !== '' && Number.isFinite(Number(env[name])) ? Number(env[name]) : null);
+    try {
+        const output = await runAgent({
+            llm: { baseUrl: env.QAIFY_AI_BASE_URL, apiKey: env.QAIFY_AI_API_KEY, provider: env.QAIFY_AI_PROVIDER ?? 'custom', model, ...(options.fetch ? { fetch: options.fetch } : {}) },
+            instructions,
+            prompt,
+            schema,
+            tools: options.tools,
+            mcp: servers,
+            maxTurns: options.maxTurns,
+            cwd: options.cwd,
+            env: safeEnv,
+            contextTokens: price('QAIFY_AI_CONTEXT') ?? undefined,
+            price: { input: price('QAIFY_AI_PRICE_INPUT'), output: price('QAIFY_AI_PRICE_OUTPUT') },
+            log,
+        });
+        log(`qaify-agent: ${output.is_error ? `gagal (${output.error_code})` : 'selesai'} · ${output.num_turns} giliran · ` +
+            `${output.usage.input_tokens + output.usage.cache_read_input_tokens} token masuk / ${output.usage.output_tokens} keluar` +
+            (output.total_cost_usd !== null ? ` · US$${output.total_cost_usd.toFixed(4)}` : ''));
+        return await write(output);
+    }
+    finally {
+        for (const server of servers)
+            server.close();
+    }
+}

package/dist/agent/llm.d.ts

@@ -0,0 +1,46 @@
+import type { ToolSpec } from './tools.js';
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    /** dikembalikan apa adanya ke provider (mis. reasoning_details OpenRouter) */
+    [extra: string]: unknown;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    cached_tokens: number;
+    /** USD dari provider (OpenRouter usage.cost); null = tidak dilaporkan */
+    cost: number | null;
+}
+export interface ChatResult {
+    message: ChatMessage;
+    finish_reason: string | null;
+    usage: ChatUsage;
+}
+export interface LlmConfig {
+    baseUrl: string;
+    apiKey: string;
+    provider: string;
+    model: string;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    /** retry 429 / 5xx / galat jaringan */
+    retries?: number;
+    timeoutMs?: number;
+}
+export declare class LlmError extends Error {
+    readonly code: 'ai_key_invalid' | 'ai_credit_low' | 'rate_limit' | 'model_no_tools' | 'model_not_found' | 'provider_error';
+    readonly status: number | null;
+    constructor(message: string, code: 'ai_key_invalid' | 'ai_credit_low' | 'rate_limit' | 'model_no_tools' | 'model_not_found' | 'provider_error', status?: number | null);
+}
+export declare function chat(config: LlmConfig, messages: ChatMessage[], tools: ToolSpec[]): Promise<ChatResult>;

package/dist/agent/llm.js

@@ -0,0 +1,111 @@
+export class LlmError extends Error {
+    code;
+    status;
+    constructor(message, code, status = null) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+const sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function chat(config, messages, tools) {
+    const doFetch = config.fetch ?? fetch;
+    const wait = config.sleep ?? sleepDefault;
+    const retries = config.retries ?? 5;
+    const url = `${config.baseUrl.replace(/\/+$/, '')}/chat/completions`;
+    const body = {
+        model: config.model,
+        messages,
+        ...(tools.length ? { tools: tools.map((t) => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.parameters } })), tool_choice: 'auto' } : {}),
+        // OpenRouter: biaya per request di usage.cost
+        ...(config.provider === 'openrouter' ? { usage: { include: true } } : {}),
+    };
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${config.apiKey}`,
+        ...(config.provider === 'openrouter' ? { 'HTTP-Referer': 'https://qaify.vercel.app', 'X-Title': 'Qaify' } : {}),
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        let res;
+        try {
+            res = await doFetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(config.timeoutMs ?? 300_000) });
+        }
+        catch (e) {
+            lastError = new LlmError(`Tidak bisa menghubungi provider: ${e.message}`, 'provider_error');
+            if (attempt < retries)
+                await wait(backoff(attempt));
+            continue;
+        }
+        const text = await res.text();
+        let data = null;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            /* body bukan JSON */
+        }
+        if (res.ok && !data?.error) {
+            const choice = data?.choices?.[0];
+            if (!choice?.message)
+                throw new LlmError(`Respons provider tanpa pilihan jawaban: ${text.slice(0, 300)}`, 'provider_error', res.status);
+            return { message: normalizeMessage(choice.message), finish_reason: choice.finish_reason ?? null, usage: readUsage(data.usage) };
+        }
+        const status = data?.error?.code && Number.isInteger(data.error.code) ? Number(data.error.code) : res.status;
+        const message = String(data?.error?.message ?? data?.message ?? text ?? res.statusText).slice(0, 500);
+        lastError = classify(status, message);
+        const retryable = status === 429 || status >= 500 || status === 408;
+        if (!retryable || attempt === retries)
+            break;
+        const after = Number(res.headers.get('retry-after'));
+        await wait(Number.isFinite(after) && after > 0 ? Math.min(after * 1000, 60_000) : backoff(attempt));
+    }
+    throw lastError ?? new LlmError('Provider tidak merespons', 'provider_error');
+}
+function classify(status, message) {
+    const lower = message.toLowerCase();
+    if (status === 401 || status === 403 || /invalid api key|incorrect api key|api key not valid|unauthorized/.test(lower)) {
+        return new LlmError(`API key ditolak provider (${status}): ${message}`, 'ai_key_invalid', status);
+    }
+    if (status === 402 || /insufficient (credits|balance|quota)|credit balance|exceeded your current quota/.test(lower)) {
+        return new LlmError(`Saldo / kredit provider habis (${status}): ${message}`, 'ai_credit_low', status);
+    }
+    if (status === 429)
+        return new LlmError(`Provider membatasi request (rate limit): ${message}`, 'rate_limit', status);
+    if (/tool|function call/.test(lower) && /support|not available|unsupported/.test(lower)) {
+        return new LlmError(`Model ini tidak mendukung tool calling: ${message}`, 'model_no_tools', status);
+    }
+    if (status === 404 || /model .*not (found|exist)|no endpoints found|invalid model/.test(lower)) {
+        return new LlmError(`Model tidak ditemukan di provider: ${message}`, 'model_not_found', status);
+    }
+    return new LlmError(`Provider membalas ${status}: ${message}`, 'provider_error', status);
+}
+function normalizeMessage(raw) {
+    const { role: _role, content, tool_calls, refusal: _refusal, ...extra } = raw ?? {};
+    const calls = Array.isArray(tool_calls)
+        ? tool_calls
+            .filter((c) => c?.function?.name)
+            .map((c, i) => ({
+            id: String(c.id || `call_${Date.now()}_${i}`),
+            type: 'function',
+            function: { name: String(c.function.name), arguments: typeof c.function.arguments === 'string' ? c.function.arguments : JSON.stringify(c.function.arguments ?? {}) },
+        }))
+        : [];
+    // reasoning (DeepSeek/Kimi/OpenRouter) disertakan kembali hanya bila berbentuk yang dikenal
+    const keep = Object.fromEntries(Object.entries(extra).filter(([k]) => k === 'reasoning_details' || k === 'reasoning_content'));
+    return {
+        role: 'assistant',
+        content: typeof content === 'string' ? content : Array.isArray(content) ? content.map((p) => p?.text ?? '').join('') : null,
+        ...(calls.length ? { tool_calls: calls } : {}),
+        ...keep,
+    };
+}
+function readUsage(u) {
+    return {
+        prompt_tokens: Number(u?.prompt_tokens ?? 0),
+        completion_tokens: Number(u?.completion_tokens ?? 0),
+        cached_tokens: Number(u?.prompt_tokens_details?.cached_tokens ?? u?.prompt_cache_hit_tokens ?? 0),
+        cost: typeof u?.cost === 'number' ? u.cost : null,
+    };
+}
+const backoff = (attempt) => Math.min(30_000, 1000 * 2 ** attempt);

package/dist/agent/mcp.d.ts

@@ -0,0 +1,31 @@
+import type { ToolSpec } from './tools.js';
+interface ServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export declare class McpServer {
+    readonly name: string;
+    private readonly config;
+    private readonly env;
+    private readonly log;
+    private child;
+    private nextId;
+    private pending;
+    private buffer;
+    readonly tools: (ToolSpec & {
+        remote: string;
+    })[];
+    constructor(name: string, config: ServerConfig, env: NodeJS.ProcessEnv, log?: (msg: string) => void);
+    start(timeoutMs?: number): Promise<void>;
+    /** Hasil tool sebagai teks; gambar diganti keterangan (tidak semua provider menerima gambar di pesan tool). */
+    call(remote: string, args: unknown, timeoutMs?: number): Promise<string>;
+    close(): void;
+    private request;
+    private notify;
+    private onData;
+    private failAll;
+}
+/** Baca .qaify/mcp.json (format Claude Code: {mcpServers: {name: {command, args, env}}}). */
+export declare function loadMcpConfig(path: string): Promise<Record<string, ServerConfig>>;
+export {};

package/dist/agent/mcp.js

@@ -0,0 +1,115 @@
+// Klien MCP stdio minimal (JSON-RPC 2.0, satu pesan per baris) untuk Playwright MCP di audit Qaify Agent.
+// Nama tool diberi prefix mcp__<server>__ seperti Claude Code agar instruksi audit yang sama tetap berlaku.
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const PROTOCOL_VERSION = '2025-06-18';
+export class McpServer {
+    name;
+    config;
+    env;
+    log;
+    child = null;
+    nextId = 1;
+    pending = new Map();
+    buffer = '';
+    tools = [];
+    constructor(name, config, env, log = () => { }) {
+        this.name = name;
+        this.config = config;
+        this.env = env;
+        this.log = log;
+    }
+    async start(timeoutMs = 180_000) {
+        this.child = spawn(this.config.command, this.config.args ?? [], { env: { ...this.env, ...this.config.env }, stdio: ['pipe', 'pipe', 'pipe'] });
+        this.child.stdout.on('data', (chunk) => this.onData(chunk.toString()));
+        this.child.stderr.on('data', (chunk) => this.log(`[mcp ${this.name}] ${chunk.toString().trimEnd()}`));
+        this.child.on('exit', (code) => this.failAll(new Error(`server MCP ${this.name} berhenti (exit ${code})`)));
+        this.child.on('error', (e) => this.failAll(e));
+        await this.request('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'qaify-agent', version: '1' } }, timeoutMs);
+        this.notify('notifications/initialized');
+        let cursor;
+        do {
+            const page = await this.request('tools/list', cursor ? { cursor } : {});
+            for (const tool of page?.tools ?? []) {
+                this.tools.push({
+                    name: `mcp__${this.name}__${tool.name}`,
+                    remote: tool.name,
+                    description: String(tool.description ?? '').slice(0, 1000),
+                    parameters: tool.inputSchema && typeof tool.inputSchema === 'object' ? tool.inputSchema : { type: 'object', properties: {} },
+                });
+            }
+            cursor = page?.nextCursor;
+        } while (cursor);
+    }
+    /** Hasil tool sebagai teks; gambar diganti keterangan (tidak semua provider menerima gambar di pesan tool). */
+    async call(remote, args, timeoutMs = 120_000) {
+        const result = await this.request('tools/call', { name: remote, arguments: args ?? {} }, timeoutMs);
+        const parts = (result?.content ?? []).map((c) => c?.type === 'text' ? String(c.text) : c?.type === 'image' ? `[gambar ${c.mimeType ?? ''} diterima]` : `[konten ${c?.type ?? '?'}]`);
+        const text = parts.join('\n') || '(kosong)';
+        return result?.isError ? `Error: ${text}` : text;
+    }
+    close() {
+        this.failAll(new Error('ditutup'));
+        this.child?.kill('SIGTERM');
+        this.child = null;
+    }
+    request(method, params, timeoutMs = 60_000) {
+        if (!this.child)
+            return Promise.reject(new Error(`server MCP ${this.name} belum berjalan`));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`${method} ke server MCP ${this.name} melewati ${Math.round(timeoutMs / 1000)} detik`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        });
+    }
+    notify(method, params) {
+        this.child?.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, ...(params ? { params } : {}) })}\n`);
+    }
+    onData(text) {
+        this.buffer += text;
+        let index;
+        while ((index = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, index).trim();
+            this.buffer = this.buffer.slice(index + 1);
+            if (!line)
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            // permintaan dari server (mis. roots/list, ping): balas kosong agar server tidak menunggu
+            if (message.method && message.id !== undefined) {
+                this.child?.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: message.id, result: message.method === 'roots/list' ? { roots: [] } : {} })}\n`);
+                continue;
+            }
+            const pending = typeof message.id === 'number' ? this.pending.get(message.id) : undefined;
+            if (!pending)
+                continue;
+            this.pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.error)
+                pending.reject(new Error(`MCP ${this.name}: ${message.error.message ?? 'error'}`));
+            else
+                pending.resolve(message.result);
+        }
+    }
+    failAll(error) {
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+            this.pending.delete(id);
+        }
+    }
+}
+/** Baca .qaify/mcp.json (format Claude Code: {mcpServers: {name: {command, args, env}}}). */
+export async function loadMcpConfig(path) {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    return parsed?.mcpServers && typeof parsed.mcpServers === 'object' ? parsed.mcpServers : {};
+}

package/dist/agent/run.d.ts

@@ -0,0 +1,56 @@
+import { type ChatMessage, type LlmConfig } from './llm.js';
+import { McpServer } from './mcp.js';
+export declare const SUBMIT_TOOL = "submit_result";
+export interface AgentOptions {
+    llm: LlmConfig;
+    /** instruksi sistem (berkas instructions.txt yang sama dengan Claude Code) */
+    instructions: string;
+    prompt: string;
+    schema: Record<string, unknown>;
+    /** nama tool lokal: read, list, grep, write, edit, bash */
+    tools: string[];
+    mcp?: McpServer[];
+    maxTurns: number;
+    cwd: string;
+    /** env untuk bash & MCP: tanpa QAIFY_AI_* */
+    env: NodeJS.ProcessEnv;
+    /** token konteks model (dari katalog); default 128k */
+    contextTokens?: number;
+    /** USD per 1 juta token, dipakai bila provider tidak melaporkan biaya */
+    price?: {
+        input: number | null;
+        output: number | null;
+    };
+    log?: (msg: string) => void;
+    now?: () => number;
+}
+export interface AgentOutput {
+    type: 'result';
+    subtype: string;
+    is_error: boolean;
+    result: string;
+    structured_output?: unknown;
+    num_turns: number;
+    duration_ms: number;
+    total_cost_usd: number | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens: number;
+    };
+    modelUsage: Record<string, {
+        outputTokens: number;
+        inputTokens: number;
+    }>;
+    engine: 'qaify_agent';
+    provider: string;
+    error_code?: string;
+}
+export declare function runAgent(options: AgentOptions): Promise<AgentOutput>;
+/**
+ * Perkiraan token = karakter / 4. Di atas 70% konteks: isi hasil tool lama dipangkas (6 pesan terakhir utuh),
+ * struktur percakapan tetap (setiap tool_call tetap punya balasan).
+ */
+export declare function trimContext(messages: ChatMessage[], contextTokens: number): void;
+/** Validator JSON Schema kecil (type, properties, required, items, enum) untuk hasil submit_result. */
+export declare function validate(schema: any, value: unknown, path?: string): string[];

package/dist/agent/run.js

@@ -0,0 +1,177 @@
+// Qaify Agent: loop agen tool-calling di runner untuk API key milik user (BYOK, OpenAI-compatible).
+// Pengganti `claude -p` untuk agen yang diatur ke mesin Qaify Agent. Keluarannya berbentuk sama dengan
+// `claude -p --output-format json --json-schema` (structured_output, usage, total_cost_usd, modelUsage) sehingga
+// audit-submit / fix-submit / ai-submit tidak perlu tahu mesin mana yang dipakai.
+import { chat, LlmError } from './llm.js';
+import { LOCAL_TOOLS, truncate } from './tools.js';
+export const SUBMIT_TOOL = 'submit_result';
+const BASE_INSTRUCTIONS = `Anda adalah Qaify Agent, agen otomatis yang bekerja tanpa manusia di runner GitHub Actions.
+- Kerjakan tugas dengan tool yang tersedia (membaca/mencari/mengubah berkas, menjalankan perintah, browser bila ada).
+- Panggil beberapa tool sekaligus bila tidak saling bergantung. Jangan bertanya ke pengguna; tidak ada yang menjawab.
+- Setelah selesai, WAJIB panggil tool ${SUBMIT_TOOL} tepat satu kali dengan hasil akhir sesuai skemanya.
+  Jangan menulis hasil akhir sebagai teks biasa.`;
+export async function runAgent(options) {
+    const now = options.now ?? Date.now;
+    const log = options.log ?? (() => { });
+    const started = now();
+    const usage = { prompt: 0, completion: 0, cached: 0, cost: 0, costKnown: true };
+    const ctx = { cwd: options.cwd, env: options.env };
+    const local = options.tools.map((name) => LOCAL_TOOLS[name]).filter((t) => !!t);
+    const remote = new Map();
+    for (const server of options.mcp ?? [])
+        for (const tool of server.tools)
+            remote.set(tool.name, { server, remote: tool.remote });
+    const specs = [
+        ...local.map(({ name, description, parameters }) => ({ name, description, parameters })),
+        ...(options.mcp ?? []).flatMap((s) => s.tools.map(({ name, description, parameters }) => ({ name, description, parameters }))),
+        { name: SUBMIT_TOOL, description: 'Kirim hasil akhir tugas (sekali, di akhir). Isi sesuai skema.', parameters: options.schema },
+    ];
+    const messages = [
+        { role: 'system', content: `${BASE_INSTRUCTIONS}\n\n${options.instructions}`.trim() },
+        { role: 'user', content: options.prompt },
+    ];
+    const finish = (subtype, isError, result, structured, errorCode, turns = 0) => ({
+        type: 'result',
+        subtype,
+        is_error: isError,
+        result,
+        ...(structured !== undefined ? { structured_output: structured } : {}),
+        num_turns: turns,
+        duration_ms: now() - started,
+        total_cost_usd: usage.costKnown ? round(usage.cost) : null,
+        usage: { input_tokens: usage.prompt - usage.cached, output_tokens: usage.completion, cache_read_input_tokens: usage.cached },
+        modelUsage: { [options.llm.model]: { outputTokens: usage.completion, inputTokens: usage.prompt } },
+        engine: 'qaify_agent',
+        provider: options.llm.provider,
+        ...(errorCode ? { error_code: errorCode } : {}),
+    });
+    let nudges = 0;
+    for (let turn = 1; turn <= options.maxTurns; turn++) {
+        trimContext(messages, options.contextTokens ?? 128_000);
+        if (turn === options.maxTurns - 1) {
+            messages.push({ role: 'user', content: `Giliran hampir habis. Segera panggil ${SUBMIT_TOOL} dengan hasil terbaik yang Anda punya.` });
+        }
+        let reply;
+        try {
+            reply = await chat(options.llm, messages, specs);
+        }
+        catch (e) {
+            const error = e instanceof LlmError ? e : new LlmError(e.message, 'provider_error');
+            log(`qaify-agent: ${error.message}`);
+            return finish(`error_${error.code}`, true, error.message, undefined, error.code, turn - 1);
+        }
+        addUsage(usage, reply.usage, options.price);
+        const message = reply.message;
+        messages.push(message);
+        const calls = message.tool_calls ?? [];
+        if (calls.length === 0) {
+            if (message.content)
+                log(`qaify-agent: ${truncate(message.content, 400)}`);
+            if (++nudges > 3)
+                return finish('error_no_result', true, `Model tidak memanggil ${SUBMIT_TOOL} setelah diingatkan.`, undefined, 'no_result', turn);
+            messages.push({ role: 'user', content: `Lanjutkan tugas memakai tool. Bila sudah selesai, panggil ${SUBMIT_TOOL} dengan hasil akhir sesuai skema.` });
+            continue;
+        }
+        for (const call of calls) {
+            let args;
+            try {
+                args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+            }
+            catch {
+                messages.push({ role: 'tool', tool_call_id: call.id, content: 'Error: argumen bukan JSON yang valid. Ulangi dengan JSON yang benar.' });
+                continue;
+            }
+            if (call.function.name === SUBMIT_TOOL) {
+                const problems = validate(options.schema, args);
+                if (problems.length === 0) {
+                    log(`qaify-agent: hasil dikirim setelah ${turn} giliran`);
+                    return finish('success', false, 'Selesai.', args, undefined, turn);
+                }
+                messages.push({ role: 'tool', tool_call_id: call.id, content: `Hasil belum sesuai skema:\n- ${problems.slice(0, 15).join('\n- ')}\nPerbaiki lalu panggil ${SUBMIT_TOOL} lagi.` });
+                continue;
+            }
+            messages.push({ role: 'tool', tool_call_id: call.id, content: await runTool(call.function.name, args, local, remote, ctx, log) });
+        }
+    }
+    return finish('error_max_turns', true, `Batas ${options.maxTurns} giliran habis sebelum hasil dikirim.`, undefined, 'max_turns', options.maxTurns);
+}
+async function runTool(name, args, local, remote, ctx, log) {
+    const tool = local.find((t) => t.name === name);
+    const target = remote.get(name);
+    if (!tool && !target)
+        return `Error: tool ${name} tidak tersedia.`;
+    log(`qaify-agent: ${name} ${truncate(JSON.stringify(args ?? {}), 160)}`);
+    try {
+        return truncate(tool ? await tool.run(args, ctx) : await target.server.call(target.remote, args));
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+}
+function addUsage(total, u, price) {
+    total.prompt += u.prompt_tokens;
+    total.completion += u.completion_tokens;
+    total.cached += u.cached_tokens;
+    if (u.cost !== null)
+        total.cost += u.cost;
+    else if (price?.input != null && price?.output != null)
+        total.cost += (u.prompt_tokens * price.input + u.completion_tokens * price.output) / 1_000_000;
+    else
+        total.costKnown = false;
+}
+/**
+ * Perkiraan token = karakter / 4. Di atas 70% konteks: isi hasil tool lama dipangkas (6 pesan terakhir utuh),
+ * struktur percakapan tetap (setiap tool_call tetap punya balasan).
+ */
+export function trimContext(messages, contextTokens) {
+    const budget = contextTokens * 0.7 * 4;
+    const size = () => messages.reduce((n, m) => n + (m.content?.length ?? 0) + JSON.stringify(m.tool_calls ?? '').length, 0);
+    if (size() <= budget)
+        return;
+    for (let i = 2; i < messages.length - 6 && size() > budget; i++) {
+        const m = messages[i];
+        if (m.role === 'tool' && (m.content?.length ?? 0) > 200)
+            m.content = '[hasil tool lama dipangkas untuk menghemat konteks]';
+        else if (m.role === 'assistant' && (m.content?.length ?? 0) > 2000)
+            m.content = `${m.content.slice(0, 500)}… [dipangkas]`;
+    }
+}
+/** Validator JSON Schema kecil (type, properties, required, items, enum) untuk hasil submit_result. */
+export function validate(schema, value, path = 'hasil') {
+    if (!schema || typeof schema !== 'object')
+        return [];
+    const errors = [];
+    const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+    if (types.length && !types.some((t) => matchesType(t, value))) {
+        return [`${path} harus bertipe ${types.join('/')}`];
+    }
+    if (schema.enum && !schema.enum.includes(value))
+        errors.push(`${path} harus salah satu dari ${JSON.stringify(schema.enum)}`);
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        for (const key of schema.required ?? []) {
+            if (value[key] === undefined)
+                errors.push(`${path}.${key} wajib diisi`);
+        }
+        for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+            const v = value[key];
+            if (v !== undefined && v !== null)
+                errors.push(...validate(sub, v, `${path}.${key}`));
+        }
+    }
+    if (Array.isArray(value) && schema.items)
+        value.forEach((v, i) => errors.push(...validate(schema.items, v, `${path}[${i}]`)));
+    return errors;
+}
+function matchesType(type, value) {
+    switch (type) {
+        case 'object': return !!value && typeof value === 'object' && !Array.isArray(value);
+        case 'array': return Array.isArray(value);
+        case 'string': return typeof value === 'string';
+        case 'boolean': return typeof value === 'boolean';
+        case 'integer': return Number.isInteger(value);
+        case 'number': return typeof value === 'number';
+        case 'null': return value === null;
+        default: return true;
+    }
+}
+const round = (n) => Math.round(n * 1_000_000) / 1_000_000;

package/dist/agent/tools.d.ts

@@ -0,0 +1,22 @@
+export interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface LocalTool extends ToolSpec {
+    run(args: any, ctx: ToolContext): Promise<string>;
+}
+export interface ToolContext {
+    cwd: string;
+    /** env untuk perintah bash (tanpa QAIFY_AI_*) */
+    env: NodeJS.ProcessEnv;
+}
+/** Nama tool (untuk --tools) → definisi. */
+export declare const LOCAL_TOOLS: Record<string, LocalTool>;
+/** Path relatif / absolut → absolut di dalam folder kerja; keluar dari folder kerja ditolak. */
+export declare function confine(cwd: string, path: unknown): string;
+/** Glob sederhana: ** (lintas folder), * dan ? (dalam satu segmen), {a,b}. */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function truncate(text: string, max?: number): string;
+/** Cek ada / tidaknya berkas (dipakai test). */
+export declare function exists(path: string): Promise<boolean>;