@htooayelwinict/appv23 2.3.0 → 2.3.2

package/README.md

@@ -23,7 +23,15 @@ The launcher pulls and runs:
 ghcr.io/htooayelwinict/appv23:production
 ```
 
-It mounts only the selected `--cwd` as `/workspace`, stores sandbox state in `~/.appv23/sandbox-home`, and copies host `~/.agents/skills` into the sandbox.
+It mounts only the selected `--cwd` as `/workspace`, stores sandbox state in `~/.appv23/sandbox-home`, copies host `~/.agents/AGENTS.md` into the sandbox agent context, and copies host `~/.agents/skills` into the sandbox.
+
+On startup, the package restores compact default agent files only when they are missing:
+
+- `~/.agents/AGENTS.md`
+- `~/.agents/skills/web-search/SKILL.md`
+- bundled package skills such as `subagent-delegation`
+
+Existing user files are never overwritten.
 
 ## Options
 

package/agents/AGENTS.md

@@ -0,0 +1,25 @@
+# appv23 Agent Kernel
+
+This is the default appv23 user-level agent prompt. It is installed only when
+`~/.agents/AGENTS.md` is missing. Edit the host file to customize behavior.
+
+## Core behavior
+
+- Treat the selected `--cwd` as the normal workspace boundary.
+- Do not read or write outside the workspace unless the user explicitly allows it.
+- Keep the main agent direct and lightweight for ordinary requests.
+- Use skills only when the user asks for that capability or the task clearly needs it.
+- Prefer concise tool use and avoid repeated no-progress tool calls.
+- Do not expose API keys, auth files, or other secrets.
+
+## Skill routing
+
+- Use `web-search` only for current public information, recent facts, news, sports/results, or explicit web-search requests.
+- Use `subagent-delegation` only for explicit subagent requests, `/subagents` workflows, review/QA delegation, or large independent workstreams.
+- For normal coding, act as the main agent without spawning subagents.
+
+## Sandbox expectations
+
+- The Docker sandbox mounts only the selected workspace and appv23 state.
+- API keys configured through `/login` live in appv23 sandbox state, not in project files.
+- If a path is blocked or outside scope, ask for explicit authorization instead of guessing.

package/bin/appv23.js

@@ -11,6 +11,7 @@ const DEFAULT_IMAGE =
 const PUBLIC_APPV23_IMAGE_PREFIX = "ghcr.io/htooayelwinict/appv23:";
 const CONTAINER_WORKSPACE = "/workspace";
 const CONTAINER_AGENT_HOME = "/agent-home";
+const IMPORTED_AGENTS_MARKER = "<!-- appv23-sandbox-imported-agents -->";
 const SKIP_IMPORT_NAMES = new Set([
   ".DS_Store",
   ".git",
@@ -222,24 +223,68 @@ function buildPullEnv(config, dockerConfig, env = process.env) {
 
 function prepareSandboxImports(config, runtime = {}) {
   const homeDir = runtime.homeDir || os.homedir();
+  const packageRoot = runtime.packageRoot || path.resolve(__dirname, "..");
   fs.mkdirSync(config.agentHome, { recursive: true, mode: 0o700 });
-  prepareAgentsFiles(config);
-  prepareSkills(config, homeDir);
+  seedHostDefaults(homeDir, packageRoot);
+  prepareAgentsFiles(config, homeDir);
+  prepareSkills(config, homeDir, packageRoot);
 }
 
-function prepareAgentsFiles(config) {
-  if (!config.agentsFiles.length) {
+function seedHostDefaults(homeDir, packageRoot) {
+  seedHostAgentsFile(homeDir, packageRoot);
+  seedHostSkills(homeDir, packageRoot);
+}
+
+function seedHostAgentsFile(homeDir, packageRoot) {
+  const source = path.join(packageRoot, "agents", "AGENTS.md");
+  const target = path.join(homeDir, ".agents", "AGENTS.md");
+  if (!fs.existsSync(source) || fs.existsSync(target)) {
     return;
   }
+  copyFileSafe(source, target);
+}
+
+function seedHostSkills(homeDir, packageRoot) {
+  const sourceRoot = path.join(packageRoot, "skills");
+  const targetRoot = path.join(homeDir, ".agents", "skills");
+  if (!fs.existsSync(sourceRoot)) {
+    return;
+  }
+  for (const child of fs.readdirSync(sourceRoot).sort()) {
+    const source = path.join(sourceRoot, child);
+    if (shouldSkipImport(source)) {
+      continue;
+    }
+    const stat = fs.statSync(source);
+    if (stat.isDirectory()) {
+      const target = path.join(targetRoot, child);
+      if (!fs.existsSync(target)) {
+        copyTreeSafe(source, target);
+      }
+    } else if (stat.isFile() && path.extname(source) === ".md") {
+      const target = path.join(targetRoot, child);
+      if (!fs.existsSync(target)) {
+        copyFileSafe(source, target);
+      }
+    }
+  }
+}
+
+function prepareAgentsFiles(config, homeDir = os.homedir()) {
+  const sources = collectAgentsFiles(config, homeDir);
   const target = path.join(config.agentHome, "agent", "AGENTS.md");
+  if (!sources.length) {
+    removeImportedAgentsFile(target);
+    return;
+  }
   const parts = [
-    "<!-- appv23-sandbox-imported-agents -->",
+    IMPORTED_AGENTS_MARKER,
     "# Imported appv23 sandbox instructions",
     "",
-    "These instructions were copied into the sandbox from explicit --agents-file arguments.",
+    "These instructions were copied into the sandbox from host ~/.agents/AGENTS.md and explicit --agents-file arguments.",
     "",
   ];
-  for (const source of config.agentsFiles) {
+  for (const source of sources) {
     const stat = fs.statSync(source);
     if (!stat.isFile()) {
       throw new Error(`agents file is not a file: ${source}`);
@@ -250,8 +295,42 @@ function prepareAgentsFiles(config) {
   fs.writeFileSync(target, parts.join("\n"), { mode: 0o600 });
 }
 
-function prepareSkills(config, homeDir) {
+function collectAgentsFiles(config, homeDir) {
+  const sources = [];
+  const userAgentsFile = path.join(homeDir, ".agents", "AGENTS.md");
+  if (fs.existsSync(userAgentsFile)) {
+    sources.push(userAgentsFile);
+  }
+  sources.push(...config.agentsFiles);
+  const deduped = [];
+  const seen = new Set();
+  for (const source of sources) {
+    const key = path.resolve(source);
+    if (seen.has(key)) {
+      continue;
+    }
+    deduped.push(key);
+    seen.add(key);
+  }
+  return deduped;
+}
+
+function removeImportedAgentsFile(target) {
+  if (!fs.existsSync(target)) {
+    return;
+  }
+  const text = fs.readFileSync(target, "utf8");
+  if (text.startsWith(IMPORTED_AGENTS_MARKER)) {
+    fs.unlinkSync(target);
+  }
+}
+
+function prepareSkills(config, homeDir, packageRoot) {
   const sources = [];
+  const bundledSkills = path.join(packageRoot, "skills");
+  if (fs.existsSync(bundledSkills)) {
+    sources.push(bundledSkills);
+  }
   const userSkills = path.join(homeDir, ".agents", "skills");
   if (config.importUserSkills && fs.existsSync(userSkills)) {
     sources.push(userSkills);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htooayelwinict/appv23",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "npx-friendly Docker launcher for the appv23 coding-agent sandbox.",
   "license": "MIT",
   "bin": {
@@ -8,7 +8,9 @@
     "appv23-sandbox": "bin/appv23.js"
   },
   "files": [
+    "agents/**/*.md",
     "bin/appv23.js",
+    "skills/**/*.md",
     "README.md",
     "package.json"
   ],

package/skills/subagent-delegation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: subagent-delegation
+description: Use only when the user explicitly asks to spawn, delegate to, hand off to, or verify work through subagents, child agents, reviewer agents, explorer agents, research agents, web-search agents, or agent-to-agent workflows.
+---
+
+# Subagent Delegation
+
+Use this skill only when the user explicitly asks for subagents, delegation, handoff, reviewer/explorer/research child agents, `/delegate`, or `/subagents`.
+
+## Default behavior
+
+- Keep the parent agent normal unless this skill is explicitly triggered.
+- This skill is active for the current user request only. After the parent reports child results, return to normal main-agent behavior.
+- Do not use this skill on a later user request unless that later request explicitly asks for subagents, delegation, handoff, reviewer/explorer/research child agents, `/delegate`, or `/subagents`.
+- Use one delegation wave by default, with at most 3 child agents.
+- Do not launch a second wave unless the user explicitly asks for it after seeing the first child summaries.
+- Do not describe or plan "Wave 2", "Wave 3", or future waves in the same answer.
+- If the task is larger than 3 children can cover, process only the first bounded slice and ask the user whether to continue.
+- Do not let children spawn more subagents.
+- Do not write files unless the user explicitly asks for written artifacts.
+
+## Scope control
+
+- If the requested scope is vague, ask one concise clarification instead of broadening it.
+- For phrases like "those files" or "those md files", use only exact files already named in the current conversation or visible parent output.
+- If no exact file list is available, ask which files or directory to use.
+- Never convert a vague request into a whole-repo or whole-workspace sweep.
+- Never run whole-workspace file-count or whole-workspace discovery commands such as `find /workspace -type f`.
+- Avoid unbounded discovery commands. Prefer a named directory and a capped listing, for example `find docs -maxdepth 1 -name '*.md' | head -20`.
+- If there are more than 12 candidate files, ask the user to narrow scope before spawning children.
+
+## Child task contract
+
+Before spawning, the parent must give each child:
+
+- A role.
+- Exact paths or one narrow directory.
+- A clear stop condition.
+- A small output budget.
+- A requirement to report status, blockers, and a concise summary.
+
+Child instructions must say:
+
+- Make one diagnostic attempt after a missing path or failed tool call, then stop and report the blocker.
+- Do not retry the same tool call with the same arguments.
+- Do not call a `glob` tool. This runtime does not provide one; use `ls`, `find`, `read`, or a bounded `bash` command when needed.
+- Do not scan parent directories outside the assigned scope.
+- Do not include full tool traces in the final answer.
+
+## Parent reporting
+
+After children finish, report only:
+
+- Child task id.
+- Child role.
+- Child status.
+- Concise child summary.
+- Any blocker or guardrail status.
+
+If a child hits a guardrail or cancellation, report it and stop. Do not retry automatically.
+
+Do not compensate for child failure by directly scanning the remaining parent scope. Report the child status and ask the user for the next step.
+
+Do not carry this workflow into the next user message. A completed child result is not permission to call more subagent tools later.

package/skills/web-search/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: web-search
+description: Use when the user explicitly asks for web search, current facts, latest news, recent public information, or sports/current-result lookup.
+---
+
+# Web Search
+
+Use this skill only for web/current-information tasks. Do not use it for local
+repo inspection, code edits, or ordinary reasoning.
+
+## Rules
+
+- Use `curl` plus Python standard library parsing.
+- Prefer Google News RSS for news/current-result lookup:
+  `https://news.google.com/rss/search?q=<encoded-query>&hl=en-US&gl=US&ceid=US:en`
+- Keep output small: show at most 5 useful results.
+- Do not print raw HTML/XML.
+- Do not write files.
+- If live search fails, say exactly what failed and suggest a direct source.
+
+## Minimal command pattern
+
+```bash
+python3 - <<'PY'
+import html
+import sys
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+
+query = " ".join(sys.argv[1:]).strip() or "latest news"
+url = "https://news.google.com/rss/search?q={}&hl=en-US&gl=US&ceid=US:en".format(
+    urllib.parse.quote_plus(query)
+)
+req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
+with urllib.request.urlopen(req, timeout=15) as response:
+    data = response.read()
+root = ET.fromstring(data)
+for index, item in enumerate(root.findall("./channel/item")[:5], 1):
+    title = html.unescape(item.findtext("title") or "").strip()
+    link = html.unescape(item.findtext("link") or "").strip()
+    pub_date = html.unescape(item.findtext("pubDate") or "").strip()
+    print(f"{index}. {title}")
+    if pub_date:
+        print(f"   date: {pub_date}")
+    if link:
+        print(f"   source: {link}")
+PY
+```
+
+Replace the query in the command with the user's requested search.