@openape/ape-agent 2.0.2 → 2.2.0

package/default-skills/bash/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: bash
+description: When a task can't be done with the other curated tools (file.read, http.get, tasks.create, mail.list, etc.), use bash — runs any shell command on the agent host through the DDISA grant cycle.
+metadata:
+  openape:
+    requires_tools: [bash]
+---
+
+# Shell access via ape-shell
+
+## What this is
+
+The `bash` tool spawns `ape-shell -c '<cmd>'` on the agent host. `ape-shell` is the human owner's interactive shell wrapper — every command goes through the OpenApe DDISA grant cycle:
+
+- Auto-approved if a YOLO scope matches (owner has pre-approved this command pattern)
+- Otherwise the owner gets a push notification on their phone with the exact command to approve or deny
+- Approval takes ~3–15s typically; budget is 5min before the call times out
+
+You run as the agent's hidden macOS user, so the filesystem and network you see are what *that* user sees — already jailed.
+
+## When to prefer bash over a curated tool
+
+Curated tools (time.now, http.get, file.read, tasks.list, mail.list) are **always preferred** when they apply:
+
+- Faster (no grant cycle)
+- Structured JSON returns instead of stdout parsing
+- Lower risk score (visible to the owner in troop UI)
+
+Reach for `bash` when:
+
+- The curated tool doesn't cover the case (e.g. `git status`, `iurio cases search`, `o365-cli mail trash <id>`)
+- You need to chain commands with pipes / loops / redirects
+- You need an auth header the deny-list strips (e.g. `curl -H 'Authorization: …'`)
+
+## Patterns
+
+Read system info:
+
+```
+bash({ "cmd": "uname -a && uptime" })
+```
+
+Run a CLI:
+
+```
+bash({ "cmd": "ape-tasks list --status open,doing --json" })
+bash({ "cmd": "iurio cases search 'foo'" })
+```
+
+Quote-heavy commands — wrap in single-quotes outside, escape inside:
+
+```
+bash({ "cmd": "find ~/Downloads -name '*.pdf' -mtime -7 -exec ls -lh {} +" })
+```
+
+Long-running command — use the `timeout_ms` param (default 5 min):
+
+```
+bash({ "cmd": "pnpm test", "timeout_ms": 180000 })
+```
+
+## Anti-patterns
+
+- **Don't** use `bash date` for the time — call `time.now` (in-process, no grant).
+- **Don't** use `bash cat ~/notes.md` for a $HOME read — call `file.read` (no grant).
+- **Don't** retry a denied/timed-out approval automatically — the owner saw the prompt and chose. Surface the timeout clearly and ask what they'd like to do.
+- **Don't** chain destructive commands in one call (`rm -rf … && …`). One destructive command per approval so the owner can decide each.
+
+## Response shape
+
+```json
+{
+  "stdout": "...",
+  "stderr": "...",
+  "exit_code": 0,
+  "timed_out": false
+}
+```
+
+Non-zero `exit_code` means the command failed — read `stderr` and decide whether to retry with a corrected command, surface the error to the user, or ask for guidance. **Don't** pretend it succeeded.

package/default-skills/file/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: file
+description: When the user asks you to read, write, or check a file in your home directory, use the file.read / file.write tools — they're $HOME-jailed and safer than bash cat.
+metadata:
+  openape:
+    requires_tools: [file.read]
+---
+
+# Files in $HOME
+
+## Jail
+
+Both tools are restricted to the agent's `$HOME` directory:
+
+- `path` is resolved relative to `$HOME` (`~/` prefix accepted, or plain `notes.md`)
+- `..` segments that would escape `$HOME` are rejected
+- 1 MB cap per read/write — anything bigger gets truncated (read) or rejected (write)
+
+For files **outside** `$HOME` (e.g. `/etc/...`, another user's directory), use `bash` with `cat`/`tee` — that goes through the DDISA grant cycle so the owner can approve broad-fs reads explicitly.
+
+## Patterns
+
+Read a JSON config:
+
+```
+file.read({ "path": "~/.openape/agent/agent.json" })
+```
+
+Append a note (read-modify-write — there's no `file.append`):
+
+```
+const r = file.read({ "path": "notes.md" })
+file.write({ "path": "notes.md", "content": r.content + "\n- new line\n" })
+```
+
+## Conventions
+
+- Paths in user prompts ("save this to notes.md") → relative to `$HOME`. Don't prefix with `/Users/...`.
+- Binary files don't round-trip via these tools (UTF-8 only). Use `bash` for non-text I/O.

package/default-skills/http/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: http
+description: When the user asks to fetch a webpage, hit a REST API, or POST JSON to an endpoint, use the http.get / http.post tools — never invent URLs.
+metadata:
+  openape:
+    requires_tools: [http.get]
+---
+
+# HTTP fetch
+
+## When to use
+
+- `http.get` — read content from any HTTPS URL (webpages, REST endpoints, JSON APIs)
+- `http.post` — POST JSON to an HTTPS URL
+
+Both are bounded:
+
+- Response capped at 1 MB (anything longer is truncated)
+- Headers go through a deny-list (no `Authorization` for arbitrary hosts, no `Cookie`)
+- HTTP-only URLs are rejected — HTTPS required
+
+For commands that go beyond simple HTTP (auth, mTLS, complex curl flags, multipart upload), use the `bash` tool with `curl` instead.
+
+## Patterns
+
+Fetch JSON:
+
+```
+http.get({
+  "url": "https://api.example.com/users/42",
+  "headers": { "Accept": "application/json" }
+})
+```
+
+POST JSON:
+
+```
+http.post({
+  "url": "https://api.example.com/notes",
+  "body": { "title": "from agent", "body": "..." },
+  "headers": { "Content-Type": "application/json" }
+})
+```
+
+## Anti-patterns
+
+- Don't synthesize URLs ("I think it's at /api/v1/foo") — ask the user for the exact endpoint or use `http.get` only after you've seen it in their message or in a tool result.
+- Don't paginate by manually incrementing offsets without checking the API's actual contract — read response shape first.
+- For auth that needs `Authorization: Bearer …`, the deny-list strips it. Use `bash` with `curl` if you need it.

package/default-skills/mail/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: mail
+description: When the user asks about their inbox — what's there, search for an email, recent unread — use mail.list / mail.search.
+metadata:
+  openape:
+    requires_tools: [mail.list]
+  openclaw:
+    # If the o365-cli binary isn't on PATH the underlying tool fails
+    # at runtime — skip the skill from the prompt so the LLM doesn't
+    # try to use it on a host where it can't run.
+    requires:
+      bins: [o365-cli]
+---
+
+# Inbox (o365-cli)
+
+## What this is
+
+Read access to the owner's Microsoft 365 inbox via the `o365-cli` tool on the agent host. The host must have `o365-cli` installed and authenticated (the owner's CLI session). If it isn't, both tools fail with a clear setup error.
+
+## When to use
+
+- `mail.list` — recent inbox messages. Optional `unread_only: true`. Default limit 20.
+- `mail.search` — keyword/from/subject search. Pass a query string.
+
+For writing, archiving, replying, or moving messages: use `bash` with explicit `o365-cli` subcommands (see `o365-cli mail --help`). Those go through the DDISA grant cycle so the owner approves each mutation.
+
+## Patterns
+
+Latest 10 unread:
+
+```
+mail.list({ "limit": 10, "unread_only": true })
+```
+
+Search by sender:
+
+```
+mail.search({ "q": "from:smaurer@deloitte.at", "limit": 20 })
+```
+
+## Conventions
+
+- Don't draft replies inside the agent if the user just asked "what's in my inbox" — listing is read-only, replies are explicit.
+- When the user wants to triage ("welche kann ich archivieren?"), list first, then offer specific candidates with message IDs — do NOT auto-move anything.
+- Account names: there are usually two — owner's primary email (Delta Mind) and a secondary (Legal Tech / DOCPIT). Ask which one if it matters.

package/default-skills/tasks/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: tasks
+description: When the user wants to see, create, or schedule a task/reminder/wiedervorlage on their personal task list, use tasks.list / tasks.create.
+metadata:
+  openape:
+    requires_tools: [tasks.list]
+  openclaw:
+    # The bash escape-hatch path uses ape-tasks; surface it as a soft
+    # dependency so on a host without ape-tasks the LLM is told this
+    # skill doesn't apply.
+    requires:
+      bins: [ape-tasks]
+---
+
+# Personal tasks (ape-tasks)
+
+## What this is
+
+The owner's personal task list at https://tasks.openape.ai — same one their `ape-tasks` CLI on Mac and the iOS app use. You're allowed to read it and add to it via the `tasks.list` and `tasks.create` tools.
+
+## When to use
+
+Use `tasks.create` whenever the user asks for any of:
+
+- "Reminder me to X tomorrow"
+- "Wiedervorlage in 2 Tagen"
+- "Add to my todo: …"
+- "Schedule X for next week"
+
+Use `tasks.list` when they ask "what's on my list", "any open tasks", "remind me what's due".
+
+## Create — parameters
+
+```
+tasks.create({
+  "title": "<short title>",
+  "notes": "<optional longer body>",
+  "priority": "low" | "med" | "high",      // default med
+  "due_at": "<ISO 8601 or relative: +2h | +1d | tomorrow 9am>"
+})
+```
+
+For wiedervorlage (mail-eskalation) the owner has a separate flow via `ape-tasks new --remind-at ...` — that path triggers email reminders. If the user wants a *reminder* (not just a todo), prefer:
+
+```
+bash({ "cmd": "ape-tasks new --title '...' --remind-at '+2d' --context-summary '...' --context-url '...'" })
+```
+
+…because the CLI has more knobs than the tool exposes (assignee, remind-at, context-url).
+
+## Conventions
+
+- Always convert relative dates from the user prompt to an absolute date in your response: "in 2 Tagen" → "am 13. Mai 2026".
+- Don't create duplicate tasks — `tasks.list` first if the user might have one already.
+- If the user asks for "remind me on …" and you only have `tasks.create`, set `due_at` and explain that the **list** will surface it, but no push notification fires unless they used `ape-tasks --remind-at`.

package/default-skills/time/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: time
+description: When the user asks for the current time, date, or wants a sanity-check that the runtime is alive, use the time.now tool — never guess.
+metadata:
+  openape:
+    requires_tools: [time.now]
+---
+
+# Time and date
+
+## When to use
+
+The `time.now` tool returns the current UTC timestamp as ISO 8601, plus the epoch in seconds and the agent host's timezone offset in minutes. Call it any time the user asks "what time is it", "what day", "how long ago was X", or as a quick "are you alive?" probe.
+
+## How to use
+
+```
+time.now({})
+```
+
+No arguments. Response shape:
+
+```json
+{
+  "iso": "2026-05-11T07:14:44Z",
+  "epoch_seconds": 1778383484,
+  "timezone_offset_minutes": 120
+}
+```
+
+## Conventions
+
+- Always report time in **both** UTC and the user's local clock when the offset is non-zero. Example: "Es ist 07:14 UTC, also 09:14 bei dir (UTC+2)."
+- For relative-time questions ("vor 3 Tagen"), compute from `epoch_seconds` — don't rely on the LLM's internal clock guess.
+- Do NOT call `bash` with `date` for the time — `time.now` is in-process and skips the DDISA grant cycle.

package/dist/bridge.mjs

@@ -1040,9 +1040,9 @@ var init_chunk_7OCVIDC7 = __esm({
 });
 
 // src/bridge.ts
-import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
-import { homedir as homedir8 } from "os";
-import { join as join8 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
+import { homedir as homedir9 } from "os";
+import { join as join9 } from "path";
 import process2 from "process";
 
 // ../../packages/cli-auth/dist/index.js
@@ -3799,6 +3799,177 @@ function shouldAutoAccept(peerEmail, identity, allowlist) {
   return allowlist.has(peer);
 }
 
+// src/skills.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { existsSync as existsSync6, readdirSync as readdirSync4, readFileSync as readFileSync7, statSync } from "fs";
+import { homedir as homedir8 } from "os";
+import { dirname as dirname2, join as join8, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+import { parse as parseYaml } from "yaml";
+var SKILLS_SUBDIR = [".openape", "agent", "skills"];
+var SOUL_PATH_PARTS = [".openape", "agent", "SOUL.md"];
+function soulPath(home = homedir8()) {
+  return join8(home, ...SOUL_PATH_PARTS);
+}
+function skillsDir(home = homedir8()) {
+  return join8(home, ...SKILLS_SUBDIR);
+}
+function readSoul(home = homedir8()) {
+  const path = soulPath(home);
+  if (!existsSync6(path)) return null;
+  try {
+    const body = readFileSync7(path, "utf8").trim();
+    return body.length > 0 ? body : null;
+  } catch {
+    return null;
+  }
+}
+function parseFrontmatter(content) {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) return null;
+  const closeIdx = trimmed.indexOf("\n---", 3);
+  if (closeIdx < 0) return null;
+  const fmBlock = trimmed.slice(3, closeIdx).trim();
+  let parsed;
+  try {
+    parsed = parseYaml(fmBlock);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const fields = parsed;
+  const name = typeof fields.name === "string" ? fields.name.trim() : "";
+  const description = typeof fields.description === "string" ? fields.description.trim() : "";
+  if (!name || !description) return null;
+  function asStringArray(v2) {
+    if (!Array.isArray(v2)) return void 0;
+    const out = v2.map((x2) => typeof x2 === "string" ? x2.trim() : "").filter((s2) => s2.length > 0);
+    return out.length > 0 ? out : void 0;
+  }
+  const meta = fields.metadata && typeof fields.metadata === "object" && !Array.isArray(fields.metadata) ? fields.metadata : {};
+  const openapeMeta = meta.openape && typeof meta.openape === "object" && !Array.isArray(meta.openape) ? meta.openape : {};
+  const openclawMeta = meta.openclaw && typeof meta.openclaw === "object" && !Array.isArray(meta.openclaw) ? meta.openclaw : {};
+  const requiresTools = asStringArray(openapeMeta.requires_tools) ?? asStringArray(fields.requires_tools);
+  function readRequiresBins(scope) {
+    const requires = scope.requires;
+    if (requires && typeof requires === "object" && !Array.isArray(requires)) {
+      return asStringArray(requires.bins);
+    }
+    return void 0;
+  }
+  const requiresBins = readRequiresBins(openclawMeta) ?? readRequiresBins(openapeMeta) ?? asStringArray(fields.requires_bins);
+  return { name, description, requiresTools, requiresBins };
+}
+var binCheckCache = /* @__PURE__ */ new Map();
+function hasBinaryOnPath(bin) {
+  const cached = binCheckCache.get(bin);
+  if (cached !== void 0) return cached;
+  let found = false;
+  try {
+    execFileSync3("/usr/bin/which", [bin], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    found = true;
+  } catch {
+  }
+  binCheckCache.set(bin, found);
+  return found;
+}
+function scanSkillsDir(dir) {
+  if (!existsSync6(dir)) return [];
+  let entries;
+  try {
+    entries = readdirSync4(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const skillPath = join8(dir, entry, "SKILL.md");
+    if (!existsSync6(skillPath)) continue;
+    let st;
+    try {
+      st = statSync(skillPath);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    let body;
+    try {
+      body = readFileSync7(skillPath, "utf8");
+    } catch {
+      continue;
+    }
+    const fm = parseFrontmatter(body);
+    if (!fm) continue;
+    out.push({
+      name: fm.name,
+      description: fm.description,
+      filePath: skillPath,
+      requiresTools: fm.requiresTools,
+      requiresBins: fm.requiresBins
+    });
+  }
+  return out;
+}
+function defaultSkillsDir() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  return resolve2(here, "..", "default-skills");
+}
+function composeSkills(home, enabledTools) {
+  const enabled = new Set(enabledTools);
+  const byName = /* @__PURE__ */ new Map();
+  for (const s2 of scanSkillsDir(defaultSkillsDir())) byName.set(s2.name, s2);
+  for (const s2 of scanSkillsDir(skillsDir(home))) byName.set(s2.name, s2);
+  const out = [];
+  for (const s2 of byName.values()) {
+    if (s2.requiresTools && s2.requiresTools.length > 0) {
+      const allPresent = s2.requiresTools.every((t2) => enabled.has(t2));
+      if (!allPresent) continue;
+    }
+    if (s2.requiresBins && s2.requiresBins.length > 0) {
+      const allBinsPresent = s2.requiresBins.every((b2) => hasBinaryOnPath(b2));
+      if (!allBinsPresent) continue;
+    }
+    out.push(s2);
+  }
+  out.sort((a2, b2) => a2.name.localeCompare(b2.name));
+  return out;
+}
+function escapeXml(s2) {
+  return s2.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function formatSkillsBlock(skills) {
+  if (skills.length === 0) return "";
+  const lines = [
+    "",
+    "The following skills provide specialized instructions for specific tasks.",
+    "Use the file.read tool to load a skill's file when the user's task matches its description.",
+    "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md) and use that absolute path in tool commands.",
+    "",
+    "<available_skills>"
+  ];
+  for (const s2 of skills) {
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeXml(s2.name)}</name>`);
+    lines.push(`    <description>${escapeXml(s2.description)}</description>`);
+    lines.push(`    <location>${escapeXml(s2.filePath)}</location>`);
+    lines.push("  </skill>");
+  }
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+function composeSystemPrompt(input) {
+  const home = input.home ?? homedir8();
+  const parts = [];
+  const soul = readSoul(home);
+  if (soul) parts.push(soul);
+  const skills = composeSkills(home, input.enabledTools);
+  const skillsBlock = formatSkillsBlock(skills);
+  if (skillsBlock) parts.push(skillsBlock);
+  const base = input.base?.trim();
+  if (base) parts.push(base);
+  return parts.join("\n\n");
+}
+
 // src/throttle.ts
 function createThrottle(fn, intervalMs) {
   let timer;
@@ -3951,20 +4122,20 @@ var ThreadSession = class {
 };
 
 // src/bridge.ts
-var AGENT_CONFIG_PATH2 = join8(homedir8(), ".openape", "agent", "agent.json");
+var AGENT_CONFIG_PATH2 = join9(homedir9(), ".openape", "agent", "agent.json");
 function resolveSystemPrompt(envFallback) {
-  if (!existsSync6(AGENT_CONFIG_PATH2)) return envFallback;
+  if (!existsSync7(AGENT_CONFIG_PATH2)) return envFallback;
   try {
-    const parsed = JSON.parse(readFileSync7(AGENT_CONFIG_PATH2, "utf8"));
+    const parsed = JSON.parse(readFileSync8(AGENT_CONFIG_PATH2, "utf8"));
     return typeof parsed.systemPrompt === "string" ? parsed.systemPrompt : envFallback;
   } catch {
     return envFallback;
   }
 }
 function resolveTools(envFallback) {
-  if (existsSync6(AGENT_CONFIG_PATH2)) {
+  if (existsSync7(AGENT_CONFIG_PATH2)) {
     try {
-      const parsed = JSON.parse(readFileSync7(AGENT_CONFIG_PATH2, "utf8"));
+      const parsed = JSON.parse(readFileSync8(AGENT_CONFIG_PATH2, "utf8"));
       if (Array.isArray(parsed.tools)) {
         return parsed.tools.filter((t2) => typeof t2 === "string");
       }
@@ -3982,10 +4153,10 @@ var RECONNECT_BASE_MS = 1e3;
 var RECONNECT_MAX_MS = 3e4;
 var ALLOWLIST_POLL_INTERVAL_MS = 3e4;
 function loadBridgeEnvFile() {
-  const path = join8(homedir8(), "Library", "Application Support", "openape", "bridge", ".env");
-  if (!existsSync6(path)) return;
+  const path = join9(homedir9(), "Library", "Application Support", "openape", "bridge", ".env");
+  if (!existsSync7(path)) return;
   try {
-    const raw = readFileSync7(path, "utf8");
+    const raw = readFileSync8(path, "utf8");
     for (const line of raw.split(/\r?\n/)) {
       const trimmed = line.trim();
       if (!trimmed || trimmed.startsWith("#")) continue;
@@ -4036,7 +4207,7 @@ function log(line) {
 `);
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function truncate(s2, n2) {
   return s2.length <= n2 ? s2 : `${s2.slice(0, n2 - 1)}\u2026`;
@@ -4139,11 +4310,16 @@ var Bridge = class {
       threadId,
       chat: this.chat,
       runtimeConfig: this.runtimeConfig(),
-      systemPrompt: resolveSystemPrompt(this.cfg.systemPrompt),
       // Tools resolve from agent.json (latest sync from troop) on
       // every new thread, so owner edits in the troop UI take
       // effect after the next sync without a bridge restart.
+      // SOUL.md + skills are merged into the system prompt the same
+      // way — picked up per-thread without restart.
       tools: resolveTools(this.cfg.tools),
+      systemPrompt: composeSystemPrompt({
+        base: resolveSystemPrompt(this.cfg.systemPrompt),
+        enabledTools: resolveTools(this.cfg.tools)
+      }),
       maxSteps: this.cfg.maxSteps,
       log
     });
@@ -4154,7 +4330,7 @@ var Bridge = class {
     const bearer = await this.bearer();
     const wsUrl = `${this.cfg.endpoint.replace(/^http/, "ws")}/api/ws?token=${encodeURIComponent(bearer.replace(/^Bearer\s+/i, ""))}`;
     const ws = new WebSocket(wsUrl);
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       let pingTimer;
       let allowlistTimer;
       ws.on("open", () => {
@@ -4187,7 +4363,7 @@ var Bridge = class {
       ws.on("close", () => {
         if (pingTimer) clearInterval(pingTimer);
         if (allowlistTimer) clearInterval(allowlistTimer);
-        resolve2();
+        resolve3();
       });
       ws.on("error", (err) => {
         if (pingTimer) clearInterval(pingTimer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openape/ape-agent",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "OpenApe agent runtime: per-agent process that connects to chat.openape.ai, runs the LLM loop with tools + cron tasks, and streams replies back to owners.",
   "type": "module",
   "license": "MIT",
@@ -11,6 +11,7 @@
   },
   "files": [
     "dist",
+    "default-skills",
     "README.md"
   ],
   "publishConfig": {
@@ -20,8 +21,9 @@
     "jose": "^5.9.0",
     "ofetch": "^1.4.1",
     "ws": "^8.18.0",
-    "@openape/cli-auth": "0.4.0",
-    "@openape/apes": "1.21.0"
+    "yaml": "^2.8.0",
+    "@openape/apes": "1.22.0",
+    "@openape/cli-auth": "0.4.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.6.1",