@4onstudios/iris-agent 0.1.0

package/dist/api/core/skills/agent-customization/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: agent-customization
+description: Create, fix, or debug agent customization files — SKILL.md, .instructions.md, .prompt.md, .agent.md, copilot-instructions.md — including frontmatter and trigger issues. Triggers - "create a custom agent/skill", "add agent instructions", "why isn't this skill triggering".
+---
+
+# Agent Customization
+
+## File types
+
+- `SKILL.md` — one skill per directory (`skills/<name>/SKILL.md`); YAML frontmatter requires `name` and `description`.
+- `.instructions.md` — global/always-on instructions.
+- `.prompt.md` — system prompt customizations.
+- `.agent.md` — agent definitions and modes.
+- `copilot-instructions.md` — VS Code Copilot repo config.
+
+## Writing effective skills
+
+- Only the frontmatter `description` is loaded into the agent prompt; the body is read on demand. Spend effort on the description.
+- Description formula: what it does + trigger phrases + "NOT for X (use Y)" disambiguation from overlapping skills. Keep it to 1-3 sentences on ONE line (multi-line YAML breaks discovery).
+- Body: imperative workflow steps and hard rules only — no capability marketing, no generic best practices.
+
+## Debugging "skill not triggering"
+
+1. Check frontmatter parses: `name:` and `description:` each on a single line at the top of the file.
+2. Check the directory layout (`skills/<dir>/SKILL.md`) and that the skill isn't disabled in user preferences.
+3. Check the description actually contains the phrases users say — vague descriptions don't match intent.
+4. Check for a duplicate `name` in another skills directory — higher-precedence dirs override.

package/dist/api/core/skills/bug-fix/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: bug-fix
+description: Diagnose and FIX a bug end-to-end — reproduce, find root cause, apply the smallest safe code change, verify with tests. Triggers - "fix this bug", "this is broken", "resolve this error", failing test/build. NOT for advisory-only recommendations without editing code (use fix-suggestions).
+---
+
+# Bug Fix
+
+## Workflow
+
+1. Gather evidence: exact error text, logs, stack trace, failing test.
+2. Reproduce the failure (or isolate a deterministic trigger) BEFORE editing code.
+3. Trace to root cause. Never patch symptoms.
+4. Apply the minimal fix, preserving existing conventions. No refactors, no unrelated changes.
+5. Validate: run the failing test plus directly related tests/lint/build.
+6. Add a regression test when practical.
+7. Report: root cause, change made, verification evidence — briefly.
+
+## Rules
+
+- If not reproducible, state assumptions and the next diagnostic steps explicitly; do not guess-fix.
+- One bug per fix. If you discover other issues, mention them; don't fix them unasked.

package/dist/api/core/skills/create-pr/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: create-pr
+description: Create a GitHub pull request from current changes — branch, commit, push, title/description, linked issues, draft or ready. Triggers - "create/open a PR", "submit as pull request", "draft PR". NOT for responding to review feedback on an existing PR (use pr-comments).
+---
+
+# Create PR
+
+## Workflow
+
+1. Verify state: `git status`, current branch, diff vs default branch. Never open a PR from the default branch — create a feature branch if needed.
+2. Commit and push outstanding changes (confirm with the user before pushing).
+3. Use the repository's PR template if one exists (`.github/PULL_REQUEST_TEMPLATE*`); otherwise use the fallback below.
+4. Title: imperative, ≤72 chars, describes the change not the activity.
+5. Link issues with closing keywords (`Fixes #123`) when applicable.
+6. Create as draft if the user wants early feedback; otherwise ready for review.
+
+## Fallback description format
+
+```
+## Summary
+What changed and why (2-4 sentences).
+
+## Testing
+How the change was verified.
+
+Fixes #<issue> (if applicable)
+```
+
+## Rules
+
+- Keep the PR focused; flag unrelated changes instead of bundling them.
+- Mention screenshots for UI changes.

package/dist/api/core/skills/dev-server/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: dev-server
+description: Start, stop, or troubleshoot local development servers — pick the right script, run as a background process, handle port conflicts, report the URL. Triggers - "start the dev server", "run the app locally", "start frontend and backend", "port already in use".
+---
+
+# Dev Server
+
+## Workflow
+
+1. Find the dev command: check `package.json` scripts (or Makefile / framework config) — never guess.
+2. Check the target port is free; if occupied, identify the process and ask before killing it, or use an alternate port.
+3. Start the server as a long-running background process (never block on it).
+4. Wait for the ready signal in output; report the URL and port.
+5. On startup failure, read the error output and fix the cause — don't blindly restart.
+
+## Rules
+
+- Multiple services (frontend + backend): start each separately and confirm each is ready.
+- Reuse an already-running healthy server instead of starting a duplicate.
+- Stop servers you started when the user is done with them.

package/dist/api/core/skills/fix-suggestions/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: fix-suggestions
+description: RECOMMEND fixes for a code issue without applying them — explain root cause, propose 1-3 options with trade-offs, recommend one. Triggers - "how do I fix", "give me options", "what's the best way to resolve", "why is this failing". NOT for actually implementing the fix (use bug-fix).
+---
+
+# Fix Suggestions
+
+Advisory only: do not edit files unless the user asks you to apply a suggestion.
+
+## Workflow
+
+1. Read the error/issue and the relevant code for context.
+2. Identify the root cause; state it in one or two sentences.
+3. Propose 1-3 solutions, each with a minimal code example.
+4. Note trade-offs only where options genuinely differ.
+5. Recommend one option with a one-line rationale and how to verify it.
+
+## Rules
+
+- Prefer one strong solution over padding to three.
+- Ground every suggestion in the actual code — no generic advice.

package/dist/api/core/skills/github-search/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: github-search
+description: Build and run GitHub search queries for issues, PRs, code, and repos using qualifier syntax (state, label, author, repo, language, dates). Triggers - "search GitHub for", "find issues/PRs about X", "find code using this pattern". NOT for formatting existing results (use search-results) or summarizing one item (use github-summary).
+---
+
+# GitHub Search
+
+## Workflow
+
+1. Translate the request into qualifier syntax; combine filters for precision.
+2. Execute the search.
+3. Return results with direct GitHub URLs and one-line context each; hand off to search-results for table formatting.
+4. If results are too broad/narrow, refine qualifiers once before asking the user.
+
+## Qualifier reference
+
+- `type:issue|pr` · `state:open|closed` · `is:merged|draft`
+- `repo:owner/name` · `org:name` · `author:user` · `assignee:user`
+- `label:"bug"` · `in:title,body` · `language:typescript`
+- `created:>2026-01-01` · `updated:<2026-06-01` · `comments:>10`
+- `sort:updated-desc` · negate with `-` (e.g. `-label:wontfix`)

package/dist/api/core/skills/github-summary/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: github-summary
+description: Summarize a single GitHub issue, PR, or notification — key points, decisions, open questions, action items. Triggers - "summarize this issue/PR", "what's this discussion about", "what are the action items". NOT for searching (use github-search).
+---
+
+# GitHub Summary
+
+## Workflow
+
+1. Fetch the full item: title, description, all comments, and for PRs the changed-files overview.
+2. Extract decisions and requirements from the discussion — weight recent comments and maintainer responses higher.
+3. Output in this format, omitting empty sections:
+
+```
+**Overview**: 1-2 sentences.
+**Key points**: bullets (max 5).
+**Decisions**: what was agreed.
+**Open questions**: unresolved items.
+**Action items**: who/what, if identifiable.
+```
+
+## Rules
+
+- Report only what is in the thread; never infer decisions that weren't made.
+- Keep the whole summary under ~150 words unless the user asks for detail.

package/dist/api/core/skills/integration-tests/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: integration-tests
+description: Generate integration tests in four layers — L1 TestContainers (DB/queue/cache in Docker), L2 smoke tests, L3 cloud/Azure integration, L4 end-to-end behavioral flows. Triggers - "add integration tests", "create TestContainers/smoke/e2e tests". NOT for unit tests.
+---
+
+# Integration Tests
+
+## Layer selection
+
+Ask which layer(s) if the user didn't specify. Default to L1 + L2.
+
+- **L1 TestContainers**: real DB/queue/cache in Docker containers; test the data/messaging boundary.
+- **L2 Smoke**: app starts, critical endpoints/happy paths respond, basic error handling.
+- **L3 Cloud (Azure)**: real service connectivity, auth flows, managed identity — requires provisioned resources; confirm they exist first.
+- **L4 Behavioral**: full user workflows across components, data consistency end-to-end.
+
+## Workflow
+
+1. Identify integration points from the code (DB clients, HTTP clients, queues, external SDKs).
+2. Use the project's existing test framework and conventions — inspect current tests first.
+3. Write fixtures with realistic data; every test must clean up its resources (containers, rows, files).
+4. Name tests after the scenario they verify, not the method they call.
+5. Run the new tests and iterate until green; then run the existing suite to confirm no interference.
+
+## Rules
+
+- Tests must be independent and order-agnostic; enable parallel execution where the framework supports it.
+- Never hardcode credentials — use env vars or the framework's secret mechanism.
+- If Docker isn't available, say so and offer L2 alternatives instead of writing untestable code.

package/dist/api/core/skills/pr-comments/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pr-comments
+description: Address review comments (including Copilot review comments) on an existing pull request — implement requested changes, reply to reviewers, resolve threads. Triggers - "address review comments", "address PR comments", "apply reviewer suggestions", "respond to PR feedback", "implement requested changes", "resolve these threads". NOT for creating a new PR (use create-pr).
+---
+
+# PR Comments
+
+## Workflow
+
+1. Fetch the PR. If its last-updated timestamp is under 3 minutes old the PR is still changing — re-fetch with a refresh so you don't act on stale threads.
+2. Collect unresolved feedback: inline threads not yet resolved, plus general review comments requesting changes.
+3. Classify each: actionable code change, question, or opinion.
+4. Implement actionable changes grouped by file; keep each change scoped to what the reviewer asked.
+5. Commit with messages referencing the feedback; push after user confirmation.
+6. Reply per thread: "Done in <commit>" for implemented items; a brief technical rationale when respectfully declining; ask for clarification when the request is ambiguous.
+7. Resolve threads only after the change is pushed or the discussion is settled, and only where the thread is actually resolvable by you.
+
+## Rules
+
+- Never resolve a thread you haven't addressed.
+- Skip threads already resolved, or that you lack permission to resolve.
+- If a suggestion would introduce a bug or conflict with another comment, say so in the reply instead of silently skipping it.
+- Report anything intentionally skipped, with the reasoning.

package/dist/api/core/skills/project-setup/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: project-setup
+description: Scaffold a complete NEW project from scratch — framework init, config files, dependencies, folder structure, verified build. Triggers - "create a new React/Next.js/Vite/Node project", "set up a workspace", "scaffold an app". NOT for adding files or features to an existing project.
+---
+
+# Project Setup
+
+## Workflow
+
+1. Confirm framework, language, and package manager from the request; ask only if genuinely ambiguous.
+2. Prefer the official scaffolding CLI (`npm create vite@latest`, `npx create-next-app`, etc.) over hand-writing config.
+3. Install dependencies with the chosen package manager.
+4. Add essentials the scaffold omits: `.gitignore`, TypeScript strictness, lint/format config if requested.
+5. Verify: run the build (and dev server briefly) to prove the setup works before handing off.
+6. Summarize the structure and the commands to run.
+
+## Rules
+
+- Use current stable versions; never pin to outdated majors.
+- Don't add tooling the user didn't ask for beyond the essentials above.

package/dist/api/core/skills/search-integration/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: search-integration
+description: Search the local workspace codebase — exact text, regex, and file-type-filtered searches with contextual results. Triggers - "find all usages of", "where is X defined/imported", "locate TODO comments", "find files matching". NOT for GitHub-wide search (use github-search).
+---
+
+# Search Integration
+
+## Workflow
+
+1. Pick the cheapest query that answers the question: exact string for identifiers; regex with alternation (`foo|bar`) to cover variants in ONE pass; glob file filters to cut noise.
+2. Run the search; if zero hits, broaden once (case variants, partial word) before concluding it's absent.
+3. Report file paths with line numbers and a snippet of surrounding context per match.
+4. Group matches by file; note total count.
+
+## Rules
+
+- Escape regex metacharacters when the user gives a literal string.
+- Distinguish definitions from usages when the user asks "where is X" — show the definition first.
+- Too many hits (>50): narrow by directory or file type instead of dumping everything.

package/dist/api/core/skills/search-results/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: search-results
+description: Format GitHub search results for display — sortable tables, filtered views, counts, side-by-side comparisons with links. Triggers - "show results in a table", "sort by comments", "only open issues", "compare these". NOT for running the search itself (use github-search).
+---
+
+# Search Results
+
+## Workflow
+
+1. Take the result set (from github-search or provided by the user); apply any requested filter/sort first.
+2. Render as a markdown table. Default columns: Title (linked) | State | Author | Created | Comments. Adjust columns to what's relevant.
+3. End with a one-line stat: total shown / total found, breakdown by state if mixed.
+
+## Rules
+
+- Every title must be a direct GitHub link.
+- Truncate titles at ~60 chars with `…`.
+- Default sort: relevance; state the sort order used when it differs.
+- >20 results: show top 20 and say how many were omitted.

package/dist/api/core/skills/typescript-upgrade/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: typescript-upgrade
+description: Upgrade npm dependencies in a TypeScript project and resolve breaking changes — staged upgrades, type-check verification, migration of changed APIs. Triggers - "upgrade dependencies", "update TypeScript/React to latest", "resolve dependency conflict", "migrate to <major version>".
+---
+
+# TypeScript Upgrade
+
+## Workflow
+
+1. Baseline first: confirm build, type-check, and tests pass BEFORE upgrading. Fix or note pre-existing failures.
+2. Inventory: `npm outdated`; identify majors vs minors/patches.
+3. Upgrade in stages — minors/patches in one batch; each major separately.
+4. For each major: check the changelog/migration guide, upgrade, fix compile errors and changed APIs, run type-check + tests before moving to the next.
+5. Keep related packages in lockstep (e.g. `react`/`react-dom`/`@types/react`; a library and its plugins).
+6. Final gate: full build + test suite green; then commit with a summary of versions changed.
+
+## Rules
+
+- Never combine multiple major upgrades in one step — isolate failures.
+- If a major upgrade breaks and can't be fixed quickly, revert that package and report the blocker rather than leaving the repo broken.
+- Verify peer-dependency warnings; don't silence them with `--force`.

package/dist/api/data/runStore.d.ts

@@ -0,0 +1,46 @@
+export type RunLifecycleState = "queued" | "running" | "waiting_tool" | "waiting_confirmation" | "waiting_user_input" | "paused" | "succeeded" | "failed" | "cancelled";
+export type RunStopReason = "none" | "completed" | "awaiting_approval" | "awaiting_user_input" | "max_steps_reached" | "no_progress" | "max_attempts" | "error" | "cancelled";
+export type AgentRunRow = {
+    run_id: string;
+    status: string;
+    stop_reason: string;
+    objective: string | null;
+    workspace_path: string | null;
+    model_id: string | null;
+    cancel_requested?: number | null;
+    cancel_requested_at?: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type AgentRunCheckpointRow = {
+    run_id: string;
+    sequence: number;
+    lifecycle_state: string;
+    stop_reason: string;
+    event_type: string;
+    payload_json: string | null;
+    created_at: string;
+};
+export declare const isSafeRunId: (runId: string) => boolean;
+declare const persistRunLifecycleEvent: (params: {
+    runId: string;
+    lifecycleState: RunLifecycleState;
+    stopReason: RunStopReason;
+    eventType: string;
+    payload?: Record<string, unknown>;
+    objective?: string;
+    workspacePath?: string;
+    modelId?: string;
+}) => Promise<void>;
+export declare const safePersistRunLifecycleEvent: (params: Parameters<typeof persistRunLifecycleEvent>[0]) => Promise<void>;
+export declare const requestRunCancellation: (runId: string) => Promise<boolean>;
+export declare const isRunCancellationRequested: (runId: string) => Promise<boolean>;
+export declare const clearRunCancellationRequest: (runId: string) => Promise<void>;
+export declare const deleteRunDataBatch: (runIds: string[]) => Promise<void>;
+export declare const getRunSnapshot: (runId: string) => Promise<{
+    run: AgentRunRow;
+    latestCheckpoint: AgentRunCheckpointRow | null;
+} | null>;
+export declare const listRunEvents: (runId: string, afterSequence: number, limit: number) => Promise<AgentRunCheckpointRow[]>;
+export declare const asRunLifecycleState: (value: string | undefined) => RunLifecycleState;
+export {};

package/dist/api/data/runStore.js

@@ -0,0 +1,244 @@
+import os from "os";
+import path from "path";
+import fs from "fs/promises";
+import sqlite3 from "sqlite3";
+import { open } from "sqlite";
+export const isSafeRunId = (runId) => /^[A-Za-z0-9._:-]{1,160}$/.test(runId);
+const RUN_STORE_DIR = path.join(os.homedir(), ".iris");
+const RUN_STORE_DB_PATH = process.env.IRIS_AGENT_RUNS_DB_PATH || path.join(RUN_STORE_DIR, "agent-runs.sqlite");
+let runStorePromise = null;
+// Serialize all write operations so concurrent calls never overlap on one SQLite connection.
+let writeQueue = Promise.resolve();
+const enqueueWrite = (fn) => {
+    const next = writeQueue.then(fn, fn);
+    writeQueue = next.then(() => undefined, () => undefined);
+    return next;
+};
+const initializeRunStore = async () => {
+    await fs.mkdir(path.dirname(RUN_STORE_DB_PATH), { recursive: true });
+    const db = await open({
+        filename: RUN_STORE_DB_PATH,
+        driver: sqlite3.Database,
+    });
+    // Set the busy timeout before WAL because switching journal modes also needs
+    // a database lock during fresh concurrent sidecar startup.
+    await db.exec("PRAGMA busy_timeout = 5000;");
+    // Use WAL mode so readers don't block writers (and vice versa).
+    await db.exec("PRAGMA journal_mode = WAL;");
+    await db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_runs (
+      run_id TEXT PRIMARY KEY,
+      status TEXT NOT NULL,
+      stop_reason TEXT NOT NULL,
+      objective TEXT,
+      workspace_path TEXT,
+      model_id TEXT,
+      cancel_requested INTEGER NOT NULL DEFAULT 0,
+      cancel_requested_at TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+    const runColumns = (await db.all("PRAGMA table_info(agent_runs)"));
+    const hasCancelRequested = runColumns.some((column) => column.name === "cancel_requested");
+    const hasCancelRequestedAt = runColumns.some((column) => column.name === "cancel_requested_at");
+    if (!hasCancelRequested) {
+        await db.exec("ALTER TABLE agent_runs ADD COLUMN cancel_requested INTEGER NOT NULL DEFAULT 0;");
+    }
+    if (!hasCancelRequestedAt) {
+        await db.exec("ALTER TABLE agent_runs ADD COLUMN cancel_requested_at TEXT;");
+    }
+    await db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_run_checkpoints (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      run_id TEXT NOT NULL,
+      sequence INTEGER NOT NULL,
+      lifecycle_state TEXT NOT NULL,
+      stop_reason TEXT NOT NULL,
+      event_type TEXT NOT NULL,
+      payload_json TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      UNIQUE(run_id, sequence)
+    );
+  `);
+    await db.exec("CREATE INDEX IF NOT EXISTS idx_agent_run_checkpoints_run_id ON agent_run_checkpoints(run_id, sequence);");
+    return db;
+};
+const getRunStore = async () => {
+    if (!runStorePromise) {
+        runStorePromise = initializeRunStore().catch((error) => {
+            runStorePromise = null;
+            throw error;
+        });
+    }
+    return runStorePromise;
+};
+const persistRunLifecycleEvent = async (params) => {
+    return enqueueWrite(async () => {
+        const db = await getRunStore();
+        await db.exec("BEGIN IMMEDIATE TRANSACTION;");
+        try {
+            await db.run(`
+        INSERT INTO agent_runs(run_id, status, stop_reason, objective, workspace_path, model_id, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+        ON CONFLICT(run_id) DO UPDATE SET
+          status=excluded.status,
+          stop_reason=excluded.stop_reason,
+          objective=COALESCE(excluded.objective, agent_runs.objective),
+          workspace_path=COALESCE(excluded.workspace_path, agent_runs.workspace_path),
+          model_id=COALESCE(excluded.model_id, agent_runs.model_id),
+          updated_at=CURRENT_TIMESTAMP
+      `, params.runId, params.lifecycleState, params.stopReason, params.objective || null, params.workspacePath || null, params.modelId || null);
+            const sequenceRow = (await db.get("SELECT COALESCE(MAX(sequence), 0) AS maxSequence FROM agent_run_checkpoints WHERE run_id = ?", params.runId));
+            const nextSequence = (sequenceRow?.maxSequence || 0) + 1;
+            await db.run(`
+        INSERT INTO agent_run_checkpoints(
+          run_id,
+          sequence,
+          lifecycle_state,
+          stop_reason,
+          event_type,
+          payload_json,
+          created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+      `, params.runId, nextSequence, params.lifecycleState, params.stopReason, params.eventType, params.payload ? JSON.stringify(params.payload) : null);
+            await db.exec("COMMIT;");
+        }
+        catch (error) {
+            await db.exec("ROLLBACK;");
+            throw error;
+        }
+    });
+};
+export const safePersistRunLifecycleEvent = async (params) => {
+    try {
+        await persistRunLifecycleEvent(params);
+    }
+    catch (error) {
+        const err = error;
+        console.warn("[agent] Failed to persist run lifecycle event:", err.message);
+    }
+};
+export const requestRunCancellation = async (runId) => {
+    return enqueueWrite(async () => {
+        const db = await getRunStore();
+        const result = await db.run(`
+        UPDATE agent_runs
+        SET cancel_requested = 1,
+            cancel_requested_at = CURRENT_TIMESTAMP,
+            updated_at = CURRENT_TIMESTAMP
+        WHERE run_id = ?
+      `, runId);
+        return typeof result?.changes === "number" && result.changes > 0;
+    });
+};
+export const isRunCancellationRequested = async (runId) => {
+    const db = await getRunStore();
+    const row = (await db.get("SELECT cancel_requested FROM agent_runs WHERE run_id = ?", runId));
+    return Number(row?.cancel_requested || 0) === 1;
+};
+export const clearRunCancellationRequest = async (runId) => {
+    return enqueueWrite(async () => {
+        const db = await getRunStore();
+        await db.run(`
+        UPDATE agent_runs
+        SET cancel_requested = 0,
+            cancel_requested_at = NULL,
+            updated_at = CURRENT_TIMESTAMP
+        WHERE run_id = ?
+      `, runId);
+    });
+};
+const deleteRunData = async (runId) => {
+    return enqueueWrite(async () => {
+        const db = await getRunStore();
+        await db.exec("BEGIN IMMEDIATE TRANSACTION;");
+        try {
+            await db.run("DELETE FROM agent_run_checkpoints WHERE run_id = ?", runId);
+            await db.run("DELETE FROM agent_runs WHERE run_id = ?", runId);
+            await db.exec("COMMIT;");
+        }
+        catch (error) {
+            await db.exec("ROLLBACK;");
+            throw error;
+        }
+    });
+};
+export const deleteRunDataBatch = async (runIds) => {
+    const uniqueSafeRunIds = Array.from(new Set(runIds.map((value) => value.trim()).filter((value) => isSafeRunId(value))));
+    for (const runId of uniqueSafeRunIds) {
+        await deleteRunData(runId);
+    }
+};
+export const getRunSnapshot = async (runId) => {
+    const db = await getRunStore();
+    const run = (await db.get(`
+      SELECT
+        run_id,
+        status,
+        stop_reason,
+        objective,
+        workspace_path,
+        model_id,
+        cancel_requested,
+        cancel_requested_at,
+        created_at,
+        updated_at
+      FROM agent_runs
+      WHERE run_id = ?
+    `, runId));
+    if (!run)
+        return null;
+    const latestCheckpoint = (await db.get(`
+      SELECT
+        run_id,
+        sequence,
+        lifecycle_state,
+        stop_reason,
+        event_type,
+        payload_json,
+        created_at
+      FROM agent_run_checkpoints
+      WHERE run_id = ?
+      ORDER BY sequence DESC
+      LIMIT 1
+    `, runId));
+    return {
+        run,
+        latestCheckpoint: latestCheckpoint || null,
+    };
+};
+export const listRunEvents = async (runId, afterSequence, limit) => {
+    const db = await getRunStore();
+    return (await db.all(`
+      SELECT
+        run_id,
+        sequence,
+        lifecycle_state,
+        stop_reason,
+        event_type,
+        payload_json,
+        created_at
+      FROM agent_run_checkpoints
+      WHERE run_id = ? AND sequence > ?
+      ORDER BY sequence ASC
+      LIMIT ?
+    `, runId, Math.max(0, afterSequence), Math.max(1, Math.min(500, limit))));
+};
+export const asRunLifecycleState = (value) => {
+    const valid = [
+        "queued",
+        "running",
+        "waiting_tool",
+        "waiting_confirmation",
+        "waiting_user_input",
+        "paused",
+        "succeeded",
+        "failed",
+        "cancelled",
+    ];
+    if (value && valid.includes(value)) {
+        return value;
+    }
+    return "running";
+};

package/dist/api/helpers/agentUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Backend-local agent utilities.
+ *
+ * Keep this file under `api/` so the backend can be bundled standalone
+ * without importing UI-layer source modules.
+ */
+/**
+ * Truncate environment response to prevent context window overflow.
+ * Keeps beginning and end of output for context.
+ */
+export declare const truncateEnvironmentResponse: (response: string, maxChars?: number) => string;

package/dist/api/helpers/agentUtils.js

@@ -0,0 +1,23 @@
+/**
+ * Backend-local agent utilities.
+ *
+ * Keep this file under `api/` so the backend can be bundled standalone
+ * without importing UI-layer source modules.
+ */
+/**
+ * Truncate environment response to prevent context window overflow.
+ * Keeps beginning and end of output for context.
+ */
+export const truncateEnvironmentResponse = (response, maxChars = 12000) => {
+    if (!response || typeof response !== "string") {
+        return response;
+    }
+    if (response.length <= maxChars) {
+        return response;
+    }
+    // Keep 80% from beginning, 20% from end.
+    const keepChars = Math.floor(maxChars * 0.8);
+    const tailChars = maxChars - keepChars;
+    const truncatedCount = response.length - maxChars;
+    return `${response.slice(0, keepChars)}\n\n... [TRUNCATED ${truncatedCount} characters to prevent context overflow] ...\n\n${response.slice(-tailChars)}`;
+};

package/dist/api/helpers/modelTokenLimits.d.ts

@@ -0,0 +1,2 @@
+export declare const resolveModelSupportsVision: (modelId: string) => boolean;
+export declare const resolveModelInputTokenLimit: (modelId: string, fallback?: number) => number;