@easynet/agent-runtime 1.0.2 → 1.0.4

package/apps/itermbot/scripts/patch-buildin-cache.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Patch the runtime cache with the local agent-tool-buildin build.
+# Run after `npm run build` in agent-tool-buildin to pick up local changes.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LOCAL_DIR="$SCRIPT_DIR/../../../agent-tool-buildin"
+CACHE_BASE="$SCRIPT_DIR/../config/.agent/cache/easynet/agent-tool-buildin"
+
+VERSION=$(node -e "console.log(require('$LOCAL_DIR/package.json').version)")
+CACHE_DIR="$CACHE_BASE/$VERSION"
+
+if [ ! -d "$CACHE_DIR/dist" ]; then
+  echo "Cache dir not found: $CACHE_DIR/dist"
+  echo "Run itermbot once first to populate the cache, then re-run this script."
+  exit 1
+fi
+
+cp "$LOCAL_DIR/dist/src/iterm/itermRunCommandInSession.js" "$CACHE_DIR/dist/src/iterm/"
+cp "$LOCAL_DIR/dist/src/iterm/itermRunCommandInSession.d.ts" "$CACHE_DIR/dist/src/iterm/" 2>/dev/null || true
+cp "$LOCAL_DIR/dist/src/iterm/common.js" "$CACHE_DIR/dist/src/iterm/"
+cp "$LOCAL_DIR/dist/src/iterm/common.d.ts" "$CACHE_DIR/dist/src/iterm/" 2>/dev/null || true
+cp "$LOCAL_DIR/dist/core-tools-manifest.json" "$CACHE_DIR/dist/"
+
+echo "Patched cache at $CACHE_DIR with local build v$VERSION"

package/apps/itermbot/scripts/resolve-deps.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * resolve-deps.js
+ *
+ * Run automatically via `preinstall` npm hook.
+ * In CI (CI=true), rewrites file: references in package.json to npm versions
+ * so that `npm install` can resolve them without local sibling directories.
+ *
+ * Local development: no-op (CI env var is not set).
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = resolve(__dirname, '..', 'package.json');
+
+if (!process.env.CI) {
+  process.exit(0);
+}
+
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+let changed = false;
+
+for (const section of ['dependencies', 'devDependencies']) {
+  const deps = pkg[section];
+  if (!deps) continue;
+  for (const [name, version] of Object.entries(deps)) {
+    if (name.startsWith('@easynet/') && typeof version === 'string' && version.startsWith('file:')) {
+      deps[name] = 'latest';
+      changed = true;
+      console.log(`[resolve-deps] ${name}: file: → latest`);
+    }
+  }
+}
+
+if (changed) {
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  console.log('[resolve-deps] package.json updated for CI.');
+}

package/apps/itermbot/scripts/test-llm.mjs

@@ -0,0 +1,32 @@
+/**
+ * Quick LLM config test. Run from app root: npm run test:llm
+ */
+import { createAgentLlm } from "@easynet/agent-model";
+import { loadAppConfig, getModelsConfigPath } from "../dist/config.js";
+
+async function main() {
+  try {
+    const appConfig = await loadAppConfig("config/app.yaml");
+    const agentNames = Object.keys(appConfig?.app?.agent ?? {});
+    const agentName = appConfig?.app?.defaultAgent ?? agentNames[0];
+    const modelPath = getModelsConfigPath(appConfig, agentName);
+    console.log(`[test-llm] Loading LLM from ${modelPath} ...`);
+    const llm = await createAgentLlm({
+      configPath: modelPath,
+      checkConnectivity: false,
+    });
+
+    console.log("[test-llm] Invoking LLM ...");
+    const res = await llm.invoke(
+      "In one sentence, introduce yourself and say you are being used to test iTermBot's LLM config."
+    );
+
+    console.log("[test-llm] Raw response:");
+    console.log(JSON.stringify(res, null, 2));
+  } catch (err) {
+    console.error("[test-llm] Error:", err);
+    process.exit(1);
+  }
+}
+
+main();

package/apps/itermbot/skills/command-explain-and-guard/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: command-explain-and-guard
+description: Explain shell command intent, assess risk, and suggest safer alternatives.
+allowed-tools: exec.runCommand
+metadata:
+  owner: itermbot
+  domain: safety
+---
+
+# Command Explain And Guard
+
+Use this skill before executing potentially risky shell commands.
+
+## Output
+
+- command intent
+- risk level (`low|medium|high|critical`)
+- key risk reasons
+- safe alternative command
+
+## Risk policy
+
+- destructive delete (`rm -rf`, `find ... -delete`) => critical
+- force push/history rewrite => high
+- broad recursive changes => high
+- read-only inspection commands => low
+
+## Input contract
+
+- `command`: shell command string.
+
+## Output contract
+
+Return:
+
+- `intent`
+- `riskLevel`
+- `reasons[]`
+- `safeAlternative`

package/apps/itermbot/skills/command-explain-and-guard/handler.js

@@ -0,0 +1,86 @@
+function normalize(command) {
+  return String(command || "").trim();
+}
+
+function assessRisk(command) {
+  const c = command.toLowerCase();
+
+  if (!c) {
+    return {
+      intent: "No command provided.",
+      riskLevel: "medium",
+      reasons: ["Empty command cannot be assessed reliably."],
+      safeAlternative: "echo \"No command to execute\"",
+    };
+  }
+
+  if (/\brm\s+-rf\b|\bfind\b.*\b-delete\b|\bdd\s+if=/.test(c)) {
+    return {
+      intent: "Destructive filesystem operation.",
+      riskLevel: "critical",
+      reasons: [
+        "Can irreversibly delete files or overwrite data.",
+        "Scope may be broader than intended.",
+      ],
+      safeAlternative: "ls -la <target> && rm -ri <target>",
+    };
+  }
+
+  if (/\bgit\s+push\b.*\s--force\b|\bgit\s+reset\s+--hard\b|\bgit\s+clean\s+-fd\b/.test(c)) {
+    return {
+      intent: "History rewrite or aggressive workspace cleanup.",
+      riskLevel: "high",
+      reasons: [
+        "Can discard local commits or untracked work.",
+        "Hard to recover without backups/reflog.",
+      ],
+      safeAlternative: "git status && git stash push -u && git branch backup/<name>",
+    };
+  }
+
+  if (/\b(chmod|chown)\b.*\s-r\b|\bsed\s+-i\b|\bperl\s+-pi\b/.test(c)) {
+    return {
+      intent: "Recursive or in-place bulk modification.",
+      riskLevel: "high",
+      reasons: [
+        "May modify many files unintentionally.",
+        "Rollback is difficult without VCS checkpoints.",
+      ],
+      safeAlternative: "Preview targets first, then apply on a small subset.",
+    };
+  }
+
+  if (/\b(cat|ls|pwd|echo|head|tail|grep|rg|git\s+status|git\s+log)\b/.test(c)) {
+    return {
+      intent: "Read-only inspection command.",
+      riskLevel: "low",
+      reasons: ["Does not directly modify files or history."],
+      safeAlternative: command,
+    };
+  }
+
+  return {
+    intent: "General command execution.",
+    riskLevel: "medium",
+    reasons: [
+      "Side effects are unclear from command alone.",
+      "Validate scope and target before execution.",
+    ],
+    safeAlternative: "echo \"Dry-run first\" && <command>",
+  };
+}
+
+export default async function handler(args) {
+  const command = normalize(args?.command);
+  const assessed = assessRisk(command);
+
+  return {
+    result: {
+      command,
+      intent: assessed.intent,
+      riskLevel: assessed.riskLevel,
+      reasons: assessed.reasons,
+      safeAlternative: assessed.safeAlternative,
+    },
+  };
+}

package/apps/itermbot/skills/disk-usage-investigate/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: disk-usage-investigate
+description: Investigate macOS disk space usage — find the largest directories and suggest cleanup.
+metadata:
+  owner: itermbot
+  domain: diagnostics
+---
+
+# Disk Usage Investigation (macOS)
+
+Call this skill when the user asks about disk space, storage usage, or which directories are using the most space.
+
+## Strategy
+
+### 1. Global overview
+- Run `df -h` to see which mount points are most full.
+- Optionally run `diskutil list` / `diskutil apfs list` for APFS diagnostics.
+
+### 2. Top-level breakdown
+- Run `du -xhd 1 /System/Volumes/Data 2>/dev/null | sort -h` for top-level directories.
+- Drill one level deeper into the largest results (e.g. `Users`, `Library`).
+
+### 3. User home
+- Use `du -hd 1 ~` to list child directories; focus only on the largest few (>20 GB).
+- Stop drilling when the largest child is < ~5 GB.
+
+### 4. Common heavy hitters
+Check these with `du`:
+- `~/Downloads`, `~/Desktop`
+- `~/Library/Application Support/MobileSync/Backup` (iOS backups)
+- `~/Library/Mail`, `~/Library/Messages`, `~/Pictures`
+- `~/Library/Caches`, `~/Library/Containers`
+- `~/Library/Developer/Xcode`, `~/Library/Developer/CoreSimulator`, `~/Library/Developer/Xcode/DerivedData`
+- `~/Library/Containers/com.docker.docker`
+- `/opt/homebrew/Cellar`, `/opt/homebrew/Caskroom`, `~/Library/Caches/Homebrew`
+
+### 5. Time Machine snapshots
+- `tmutil listlocalsnapshots /` for diagnostics only.
+- Never run destructive cleanup automatically — summarize options and wait for user approval.
+
+### 6. Reporting
+- Produce a structured summary: overall usage, top contributors by path/size, cleanup candidates with risk level.
+- Focus on biggest contributors; avoid broad or deep recursive scans.
+- Use `output` from each command to decide next steps — don't fire commands blindly.

package/apps/itermbot/skills/disk-usage-investigate/handler.js

@@ -0,0 +1,12 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function handler() {
+  const md = await readFile(join(__dirname, "SKILL.md"), "utf-8");
+  // Strip YAML frontmatter, return only instructions body
+  const body = md.replace(/^---[\s\S]*?---\s*/, "").trim();
+  return { result: { instructions: body } };
+}

package/apps/itermbot/skills/gpu-ssh-monitor/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gpu-ssh-monitor
+description: Login to boqiang@ssh.easynet.world and monitor NVIDIA GPU status using nvidia-smi (watch mode preferred).
+allowed-tools: itermRunCommandInSession
+metadata:
+  owner: itermbot
+  domain: ops
+---
+
+# GPU SSH Monitor
+
+Use this skill when the user asks to check remote NVIDIA GPU status on `boqiang@ssh.easynet.world`.
+
+## Non-negotiable rules
+
+- Run all commands in the iTerm target panel via `itermRunCommandInSession`.
+- Do not use local machine commands for data collection.
+- Show exact terminal evidence before summary.
+- Do not run `nvidia-smi` before SSH context is confirmed on `ssh.easynet.world`.
+
+## Workflow
+
+1. Connect remote host:
+   - `ssh boqiang@ssh.easynet.world`
+2. Confirm remote context before any GPU command:
+   - `hostname && whoami`
+   - Must show remote host/user evidence consistent with `ssh.easynet.world` / `boqiang`.
+   - If still local shell, stop and ask user to complete SSH login in target panel.
+3. Verify GPU command availability:
+   - `nvidia-smi`
+   - If output contains `command not found` / `not recognized` / missing driver errors:
+     - Stop monitoring workflow immediately.
+     - Report only failure evidence from terminal output.
+     - Suggest next checks on remote host:
+       - `which nvidia-smi`
+       - `echo $PATH`
+       - `uname -a`
+       - `cat /etc/os-release`
+       - `ls -l /usr/bin/nvidia-smi /usr/local/bin/nvidia-smi 2>/dev/null`
+     - Do not report GPU model/memory/utilization fields when `nvidia-smi` is unavailable.
+4. Start live monitor:
+   - Preferred: `watch -n 1 nvidia-smi`
+   - Fallback when `watch` is unavailable:
+     - `while true; do clear; nvidia-smi; sleep 1; done`
+5. Stop monitor:
+   - `Ctrl+C`
+
+## Reporting format
+
+- First show key terminal output in fenced `text` code blocks.
+- Then provide a short summary:
+  - GPU count and model
+  - Memory usage per GPU
+  - GPU utilization and temperature
+  - Any obvious anomaly (e.g. 0 MiB but high util, ECC/Xid errors)
+- If `nvidia-smi` failed, summary must only contain:
+  - failure reason from output,
+  - one concrete next command,
+  - no unrelated environment/file observations.
+
+## Notes
+
+- If SSH prompts for host key confirmation, proceed with user confirmation.
+- If password or MFA is required, ask user to complete it in the target panel.

package/apps/itermbot/skills/repo-triage/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: repo-triage
+description: Triage a repository task and produce entry points, risks, and an execution checklist.
+allowed-tools: fs.listDir, fs.readText, fs.searchText, git.status, git.diff
+metadata:
+  owner: itermbot
+  domain: engineering
+---
+
+# Repo Triage
+
+Use this skill when a user asks for a code change and you need a practical first pass.
+
+## What to produce
+
+1. A short plan summary tied to the user goal.
+2. Likely entry files to inspect first.
+3. Main risks and assumptions.
+4. A concrete execution checklist.
+
+## Guardrails
+
+- Do not claim certainty if you only have partial repo data.
+- Prefer high-signal files: app entry, router, service layer, tests, config.
+- Explicitly call out missing tests as a risk.
+
+## Input contract
+
+- `goal`: user objective in one sentence.
+- `scopePath`: module or directory scope.
+- `changedFiles` (optional): known touched files.
+
+## Output contract
+
+Return:
+
+- `summary`
+- `entryFiles[]`
+- `risks[]`
+- `checklist[]`

package/apps/itermbot/skills/repo-triage/handler.js

@@ -0,0 +1,56 @@
+const ENTRY_HINTS = [
+  /app\.(ts|tsx|js|mjs)$/i,
+  /main\.(ts|tsx|js|mjs)$/i,
+  /index\.(ts|tsx|js|mjs)$/i,
+  /router\.(ts|tsx|js|mjs)$/i,
+  /config\.(ts|tsx|js|mjs|yaml|yml|json)$/i,
+  /service/i,
+  /controller/i,
+  /test|spec/i,
+];
+
+function uniq(list) {
+  return Array.from(new Set(list.filter(Boolean)));
+}
+
+function pickEntryFiles(changedFiles) {
+  const files = Array.isArray(changedFiles) ? changedFiles : [];
+  if (files.length === 0) return [];
+  const prioritized = files.filter((f) => ENTRY_HINTS.some((re) => re.test(String(f))));
+  return uniq((prioritized.length > 0 ? prioritized : files).slice(0, 8));
+}
+
+export default async function handler(args) {
+  const goal = typeof args?.goal === "string" ? args.goal.trim() : "";
+  const scopePath = typeof args?.scopePath === "string" ? args.scopePath.trim() : ".";
+  const changedFiles = Array.isArray(args?.changedFiles) ? args.changedFiles.map(String) : [];
+
+  const entryFiles = pickEntryFiles(changedFiles);
+
+  const risks = [
+    "Behavior regression in adjacent modules not listed in changedFiles.",
+    "Missing or stale tests for the modified path.",
+    "Config drift between development and production environments.",
+  ];
+
+  const checklist = [
+    `Clarify acceptance criteria for: ${goal || "target change"}.`,
+    `Inspect ${scopePath} for entrypoint and dependency boundaries.`,
+    "Implement minimal change set before refactor.",
+    "Run focused tests and one end-to-end sanity check.",
+    "Document tradeoffs and any known limitations.",
+  ];
+
+  const summary = goal
+    ? `Triage for goal \"${goal}\" under \"${scopePath}\" with a low-risk execution path.`
+    : `Triage for scope \"${scopePath}\" with a low-risk execution path.`;
+
+  return {
+    result: {
+      summary,
+      entryFiles,
+      risks,
+      checklist,
+    },
+  };
+}

package/apps/itermbot/skills/test-failure-diagnose/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: test-failure-diagnose
+description: Diagnose failing tests and generate root cause, confidence, and fix plan.
+allowed-tools: fs.readText, fs.searchText, exec.runCommand
+metadata:
+  owner: itermbot
+  domain: testing
+---
+
+# Test Failure Diagnose
+
+Use this skill for red CI or local failing tests.
+
+## Goals
+
+1. Classify failure type quickly.
+2. Propose the smallest plausible fix.
+3. Provide verification steps.
+
+## Classification buckets
+
+- dependency/setup
+- type/lint
+- assertion mismatch
+- snapshot drift
+- timeout/flaky
+- unknown
+
+## Input contract
+
+- `testCommand`: command used to run tests.
+- `logText`: failing output text.
+- `failingTests` (optional): list of failing test names.
+
+## Output contract
+
+Return:
+
+- `rootCause`
+- `category`
+- `confidence` (0-1)
+- `fixPlan[]`
+- `verification[]`

package/apps/itermbot/skills/test-failure-diagnose/handler.js

@@ -0,0 +1,107 @@
+function has(text, re) {
+  return re.test(text);
+}
+
+function classify(logText) {
+  const t = logText.toLowerCase();
+
+  if (has(t, /cannot find module|module not found|enoent|missing script|not installed/)) {
+    return {
+      category: "dependency/setup",
+      rootCause: "Dependency or test runtime setup is missing or misconfigured.",
+      confidence: 0.87,
+      fixPlan: [
+        "Verify lockfile and reinstall dependencies in a clean environment.",
+        "Check test config paths and required env vars.",
+        "Re-run only the failing suite to confirm setup issue is resolved.",
+      ],
+    };
+  }
+
+  if (has(t, /ts\d{4}|typescript error|type .* is not assignable|eslint|prettier/)) {
+    return {
+      category: "type/lint",
+      rootCause: "Type checking or lint rule violation blocks test run.",
+      confidence: 0.84,
+      fixPlan: [
+        "Fix the first reported type/lint error instead of bulk-editing.",
+        "Re-run typecheck/lint target before full test run.",
+        "Add a regression test if the fix changes behavior.",
+      ],
+    };
+  }
+
+  if (has(t, /expected:|received:|toequal|tobe|assertionerror/)) {
+    return {
+      category: "assertion mismatch",
+      rootCause: "Implementation output no longer matches test expectations.",
+      confidence: 0.8,
+      fixPlan: [
+        "Inspect the failing assertion and compare old vs new behavior.",
+        "Fix implementation if behavior regressed; otherwise update test expectations intentionally.",
+        "Re-run nearby tests for related behavior.",
+      ],
+    };
+  }
+
+  if (has(t, /snapshot|does not match stored snapshot|obsolete snapshot/)) {
+    return {
+      category: "snapshot drift",
+      rootCause: "Snapshot output drifted from committed baseline.",
+      confidence: 0.9,
+      fixPlan: [
+        "Review snapshot diff for unintended output changes.",
+        "Update snapshot only after confirming behavior is expected.",
+        "Add assertion-based checks for critical fields to reduce snapshot brittleness.",
+      ],
+    };
+  }
+
+  if (has(t, /timed out|timeout|jest did not exit|flaky|retry/)) {
+    return {
+      category: "timeout/flaky",
+      rootCause: "Async timing or resource contention causes unstable test completion.",
+      confidence: 0.73,
+      fixPlan: [
+        "Identify unresolved async handles and await all background work.",
+        "Stabilize time/network dependencies with mocks.",
+        "Run the failing test repeatedly to verify flake reduction.",
+      ],
+    };
+  }
+
+  return {
+    category: "unknown",
+    rootCause: "Unable to classify failure from current logs.",
+    confidence: 0.4,
+    fixPlan: [
+      "Capture complete failing logs with verbose mode.",
+      "Narrow down to one failing test and isolate minimal reproduction.",
+      "Inspect recent diffs affecting test setup or core logic.",
+    ],
+  };
+}
+
+export default async function handler(args) {
+  const testCommand = typeof args?.testCommand === "string" ? args.testCommand : "";
+  const logText = typeof args?.logText === "string" ? args.logText : "";
+  const failingTests = Array.isArray(args?.failingTests) ? args.failingTests.map(String) : [];
+
+  const diagnosis = classify(logText);
+
+  return {
+    result: {
+      testCommand,
+      failingTests,
+      category: diagnosis.category,
+      rootCause: diagnosis.rootCause,
+      confidence: diagnosis.confidence,
+      fixPlan: diagnosis.fixPlan,
+      verification: [
+        "Run the previously failing test file in isolation.",
+        "Run related suite and one full project test run.",
+        "Ensure CI environment reproduces the same pass state.",
+      ],
+    },
+  };
+}

package/apps/itermbot/src/config.ts

@@ -0,0 +1,95 @@
+import { asObject, resolveKindResourceFile } from "@easynet/agent-common";
+import {
+  createRuntimeConfig,
+  getModelsConfigPath as getRuntimeModelsConfigPath,
+  getMemoryConfigPath as getRuntimeMemoryConfigPath,
+  getToolConfigPath as getRuntimeToolConfigPath,
+  resolveDefaultAgentName as resolveRuntimeDefaultAgentName,
+  type AgentRuntimeConfig,
+} from "@easynet/agent-runtime";
+
+type PromptTemplates = {
+  itermPolicy?: string;
+  targetSession?: string;
+};
+
+type ItermAppSpec = {
+  agent?: string;
+  printSteps?: boolean;
+  fallbackText?: string;
+  commandWindowLabel?: string;
+  promptTemplates?: PromptTemplates;
+};
+
+export type AppConfig = AgentRuntimeConfig & {
+  app?: (AgentRuntimeConfig["app"] & {
+    defaultAgent?: string;
+    printSteps?: boolean;
+    fallbackText?: string;
+    commandWindowLabel?: string;
+    promptTemplates?: PromptTemplates;
+  });
+};
+
+export interface AppConfigDefaults {
+  modelsPath?: string;
+  memoryPath?: string;
+  toolPath?: string;
+  toolDevPath?: string;
+  toolProdPath?: string;
+}
+
+export async function loadAppConfig(configPath?: string): Promise<AppConfig> {
+  const appResource = await resolveKindResourceFile<ItermAppSpec>(configPath ?? "config/app.yaml", {
+    baseDir: process.cwd(),
+    expectedApiVersion: "easynet.world/v1",
+    expectedKind: "AppConfig",
+  });
+  const spec = asObject(appResource.spec) as ItermAppSpec | undefined;
+  const runtimeConfig = await createRuntimeConfig({
+    configPath,
+    overrides: {
+      app: {
+        defaultAgent: spec?.agent,
+        printSteps: spec?.printSteps,
+        fallbackText: spec?.fallbackText,
+        commandWindowLabel: spec?.commandWindowLabel,
+        promptTemplates: spec?.promptTemplates,
+      },
+    },
+  });
+  const defaultAgent = resolveRuntimeDefaultAgentName(
+    runtimeConfig,
+    (runtimeConfig.app?.defaultAgent as string | undefined) ?? spec?.agent,
+  );
+  return {
+    app: {
+      ...runtimeConfig.app,
+      defaultAgent,
+    },
+  };
+}
+
+export function getModelsConfigPath(
+  config: AppConfig,
+  agentName?: string,
+  defaults?: AppConfigDefaults,
+): string {
+  return getRuntimeModelsConfigPath(config, agentName, defaults);
+}
+
+export function getMemoryConfigPath(
+  config: AppConfig,
+  agentName?: string,
+  defaults?: AppConfigDefaults,
+): string {
+  return getRuntimeMemoryConfigPath(config, agentName, defaults);
+}
+
+export function getToolConfigPath(
+  config: AppConfig,
+  agentName?: string,
+  defaults?: AppConfigDefaults,
+): string {
+  return getRuntimeToolConfigPath(config, agentName, defaults);
+}