@ashulab/agent-forge 0.4.0 → 0.6.0

package/README.md

@@ -9,7 +9,7 @@ On each run the launcher:
 - detects installed provider CLIs on your PATH
 - asks which provider to use (or takes it from a flag)
 - starts the provider with the GitHub token and a per-agent git identity injected into the environment
-- injects the agent's `systemPrompt` per process (`claude --append-system-prompt`, `codex -c developer_instructions`; antigravity falls back to an `AGENTS.md` block)
+- injects an identity prompt per process — a fixed block naming the git author identity and the `GH_TOKEN` / `GITHUB_TOKEN` in the environment, with the agent's optional `systemPrompt` appended (`claude --append-system-prompt`, `codex -c developer_instructions`; antigravity via a global custom agent selected with `--agent`) — no repo file is touched
 
 Provider auth stays in the provider CLI — the launcher never handles provider API keys.
 
@@ -134,7 +134,7 @@ Before launching, it prints a summary:
 │  expires   ~59m               ← installation tokens last ~1h
 ```
 
-(The `antigravity` provider adds a `memory` row pointing at the `AGENTS.md` it wrote.)
+(The `antigravity` provider adds an `agent` row showing the `--agent` id and the custom-agent file it wrote.)
 
 Other commands:
 
@@ -146,11 +146,11 @@ agent-forge --help
 
 ### Provider-specific prompt behavior
 
-`systemPrompt` is injected per process — no repo file is touched:
+The identity prompt (identity block + the agent's optional `systemPrompt`) is injected per process — no repo file is touched:
 
 - `claude`: `--append-system-prompt` (lands in the real system prompt)
 - `codex`: `-c developer_instructions=…` (appends a developer message; unlike `model_instructions_file` it does not replace codex's base prompt)
-- `antigravity` (`agy`): no such flag — the launcher writes `systemPrompt` into `AGENTS.md` in the working directory, inside a managed `agent-forge:identity` block. Do not commit it. Run one agent per worktree.
+- `antigravity` (`agy`): no prompt flag — the launcher writes the identity prompt as a global antigravity custom agent at `~/.gemini/config/agents/<name>/agent.md` (frontmatter `name`, `mainAgent: true`, `agentForge: true`; prompt under an `# Identity` heading) and passes `--agent <name>`. The file is keyed by the agent's registry `name`, upserted on each run, and never deleted. If a file with that name exists without our `agentForge` marker, the launch fails rather than overwrite it — rename the agent or remove that file.
 
 ## Token refresh
 

package/dist/launcher.cjs

@@ -4016,7 +4016,6 @@ var require_jsonwebtoken = __commonJS({
 
 // src/launcher.js
 var import_node_child_process3 = require("node:child_process");
-var import_node_path4 = require("node:path");
 var import_node_util4 = require("node:util");
 
 // node_modules/.pnpm/@clack+core@1.4.3/node_modules/@clack/core/dist/index.mjs
@@ -5220,6 +5219,7 @@ var import_node_fs = require("node:fs");
 var import_node_os = require("node:os");
 var import_node_path = require("node:path");
 var REQUIRED_FIELDS = ["name", "appId", "privateKeyPath"];
+var VALID_NAME = /^[a-z0-9][a-z0-9-]*$/;
 var SCHEMA_URL = "https://raw.githubusercontent.com/AshuLab/agent-forge/main/schema/agents.schema.json";
 var CONFIG_HOME = process.env.XDG_CONFIG_HOME || (0, import_node_path.join)((0, import_node_os.homedir)(), ".config");
 var GLOBAL_CONFIG = (0, import_node_path.join)(CONFIG_HOME, "agent-forge", "agents.json");
@@ -5264,6 +5264,11 @@ function validateAgents(agents) {
         throw new Error(`agents.json: agent ${ref} is missing "${field}"`);
       }
     }
+    if (!VALID_NAME.test(agent.name)) {
+      throw new Error(
+        `agents.json: agent ${ref} has an invalid name "${agent.name}" (lowercase letters, digits, hyphens)`
+      );
+    }
     if (seen.has(agent.name)) {
       throw new Error(`agents.json: duplicate agent name "${agent.name}"`);
     }
@@ -5343,10 +5348,17 @@ async function githubApi(path, { jwtToken, body } = {}) {
   });
   const data = await response.json();
   if (!response.ok) {
-    throw new Error(`GitHub API ${path}: ${response.status} ${data?.message || "Unknown error"}`);
+    throw new Error(githubApiError(path, response.status, data?.message, Boolean(jwtToken)));
   }
   return data;
 }
+function githubApiError(path, status, message, signedWithJwt) {
+  let text2 = `GitHub API ${path}: ${status} ${message || "Unknown error"}`;
+  if (status === 401 && signedWithJwt) {
+    text2 += " \u2014 the App JWT was rejected. Check that appId matches privateKeyPath (this key must belong to that App), and that the system clock is accurate.";
+  }
+  return text2;
+}
 async function resolveBotId(agent) {
   if (agent.botId) return String(agent.botId);
   const handle = `${agent.botName || agent.name}[bot]`;
@@ -5469,46 +5481,82 @@ function getProviderInfo(providerName, agent) {
   const resolvedCommand = isCommandInstalled(command) ? command : (provider.aliases || []).find((alias) => isCommandInstalled(alias)) || command;
   return { provider, command: resolvedCommand };
 }
-function getProviderPromptArgs(providerName, agent) {
-  const prompt = agent.systemPrompt || agent.instructions || agent.identityPrompt;
-  if (!prompt) {
-    return [];
-  }
+function getProviderPromptArgs(providerName, prompt) {
   if (providerName === "claude") return ["--append-system-prompt", prompt];
   if (providerName === "codex") return ["-c", `developer_instructions=${JSON.stringify(prompt)}`];
   return [];
 }
+function buildProviderArgs(providerName, prompt, antigravityAgent) {
+  return [
+    ...getProviderPromptArgs(providerName, prompt),
+    ...antigravityAgent ? ["--agent", antigravityAgent.name] : []
+  ];
+}
 
-// src/identity.js
+// src/agent-file.js
 var import_node_fs3 = require("node:fs");
+var import_node_os3 = require("node:os");
 var import_node_path3 = require("node:path");
-var START = "<!-- agent-forge:identity:start -->";
-var END = "<!-- agent-forge:identity:end -->";
-var MEMORY_FILE = { antigravity: "AGENTS.md" };
-function upsertIdentityBlock(content, prompt) {
-  const block2 = `${START}
-${prompt}
-${END}`;
-  const start = content.indexOf(START);
-  const end = content.indexOf(END);
-  if (start !== -1 && end > start) {
-    return content.slice(0, start) + block2 + content.slice(end + END.length);
-  }
-  return content ? `${content.trimEnd()}
-
-${block2}
-` : `${block2}
-`;
+var MARKER = "agentForge: true";
+var MARKER_LINE = /^agentForge:\s*true\s*$/m;
+function isManagedByAgentForge(text2) {
+  const end = text2.startsWith("---\n") ? text2.indexOf("\n---", 4) : -1;
+  return end !== -1 && MARKER_LINE.test(text2.slice(0, end));
+}
+var AGENTS_HOME = (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".gemini", "config", "agents");
+var VALID_NAME2 = /^[a-z0-9][a-z0-9-]*$/;
+function renderAgentFile(name, prompt) {
+  return [
+    "---",
+    `name: ${name}`,
+    "mainAgent: true",
+    MARKER,
+    "---",
+    "",
+    "# Identity",
+    "",
+    prompt.trimEnd(),
+    ""
+  ].join("\n");
 }
-function syncIdentityFile(providerName, agent, cwd = process.cwd()) {
-  const prompt = agent.systemPrompt || agent.instructions || agent.identityPrompt;
-  const name = MEMORY_FILE[providerName];
-  if (!prompt || !name) return null;
-  const file = (0, import_node_path3.join)(cwd, name);
-  const current = (0, import_node_fs3.existsSync)(file) ? (0, import_node_fs3.readFileSync)(file, "utf8") : "";
-  const next = upsertIdentityBlock(current, prompt);
-  if (next !== current) (0, import_node_fs3.writeFileSync)(file, next);
-  return file;
+function syncAntigravityAgent(agent, prompt, agentsHome = AGENTS_HOME) {
+  const name = agent.name;
+  if (!VALID_NAME2.test(name)) {
+    throw new Error(
+      `Agent name "${name}" is not a valid antigravity agent id (lowercase letters, digits, hyphens).`
+    );
+  }
+  const dir = (0, import_node_path3.join)(agentsHome, name);
+  const file = (0, import_node_path3.join)(dir, "agent.md");
+  const next = renderAgentFile(name, prompt);
+  if ((0, import_node_fs3.existsSync)(file)) {
+    const current = (0, import_node_fs3.readFileSync)(file, "utf8");
+    if (!isManagedByAgentForge(current)) {
+      throw new Error(
+        `${file} already exists and is not managed by agent-forge.
+Rename the agent in your registry or remove that file.`
+      );
+    }
+    if (next !== current) (0, import_node_fs3.writeFileSync)(file, next);
+    return { file, name };
+  }
+  (0, import_node_fs3.mkdirSync)(dir, { recursive: true });
+  (0, import_node_fs3.writeFileSync)(file, next);
+  return { file, name };
+}
+
+// src/identity-prompt.js
+function buildIdentityPrompt({ name, email }, agentPrompt) {
+  const base = [
+    "You are operating under a GitHub App identity that agent-forge set up for this session; a human is driving it interactively.",
+    "",
+    `Your commits are authored as \`${name}\` <${email}> \u2014 already configured via GIT_AUTHOR_*/GIT_COMMITTER_*, do not change it.`,
+    "A scoped, short-lived GitHub App installation token is available in the environment as GH_TOKEN and GITHUB_TOKEN; use it for `gh` and authenticated `git` operations."
+  ].join("\n");
+  const own = agentPrompt?.trim();
+  return own ? `${base}
+
+${own}` : base;
 }
 
 // src/format.js
@@ -5534,7 +5582,7 @@ var import_node_util3 = require("node:util");
 // package.json
 var package_default = {
   name: "@ashulab/agent-forge",
-  version: "0.4.0",
+  version: "0.6.0",
   description: "Give claude/codex/antigravity their own GitHub identity: a bot account, a scoped token minted per run, git attribution to match",
   license: "MIT",
   author: "Diego Ghersi <ghersidl@gmail.com>",
@@ -5658,8 +5706,23 @@ async function addAgentWizard({ embedded = false } = {}) {
   }
   const where = meta.installations.length === 1 ? `${meta.installations[0].account} \u2014 resolved automatically each run` : `${meta.installations.map((i2) => i2.account).join(", ")} \u2014 resolved from the repo you launch in`;
   note(where, "Installation");
-  const name = (keep(await text({ message: "Agent name", placeholder: meta.slug, defaultValue: meta.slug })) || meta.slug).trim();
+  const name = (keep(await text({
+    message: "Agent name",
+    placeholder: meta.slug,
+    defaultValue: meta.slug,
+    validate: (v) => /^[a-z0-9][a-z0-9-]*$/.test(v.trim()) ? void 0 : "Lowercase letters, digits, hyphens"
+  })) || meta.slug).trim();
   const label = (keep(await text({ message: "Label", placeholder: meta.name, defaultValue: meta.name })) || meta.name).trim();
+  note(
+    [
+      "agent-forge already tells every launched agent:",
+      "  \xB7 its bot git identity (GIT_AUTHOR_*/GIT_COMMITTER_*)",
+      "  \xB7 that a scoped GH_TOKEN / GITHUB_TOKEN is in the environment",
+      "",
+      "Add only what is specific to this agent \u2014 role, style, guardrails."
+    ].join("\n"),
+    "Identity is handled for you"
+  );
   const systemPrompt = keep(await text({ message: "System prompt (optional)", placeholder: "You are ..." })).trim();
   const agent = {
     name,
@@ -5787,7 +5850,11 @@ async function launchAgent(agentName, providerName) {
   const botId = await resolveBotId(agent);
   const gitIdentity = buildGitIdentity(agent, botId);
   s.stop(`Token ready for ${(0, import_node_util4.styleText)("green", gitIdentity.GIT_AUTHOR_NAME)}`);
-  const identityFile = syncIdentityFile(providerName, agent);
+  const identityPrompt = buildIdentityPrompt(
+    { name: gitIdentity.GIT_AUTHOR_NAME, email: gitIdentity.GIT_AUTHOR_EMAIL },
+    agent.systemPrompt || agent.instructions || agent.identityPrompt
+  );
+  const antigravityAgent = providerName === "antigravity" ? syncAntigravityAgent(agent, identityPrompt) : null;
   const runtimeEnv = {
     ...process.env,
     GITHUB_TOKEN: githubToken,
@@ -5808,11 +5875,11 @@ async function launchAgent(agentName, providerName) {
     row("scope", (0, import_node_util4.styleText)("dim", repositorySelection === "selected" ? `${scopeText}  \xB7  selected repos` : scopeText))
   );
   if (expiresAt) summary.push(row("expires", (0, import_node_util4.styleText)("dim", formatExpiry(expiresAt))));
-  if (identityFile) {
-    summary.push(row("memory", (0, import_node_util4.styleText)("dim", (0, import_node_path4.relative)(process.cwd(), identityFile) || identityFile)));
+  if (antigravityAgent) {
+    summary.push(row("agent", (0, import_node_util4.styleText)("dim", `--agent ${antigravityAgent.name}  \xB7  ${antigravityAgent.file}`)));
   }
   note(summary.join("\n"), (0, import_node_util4.styleText)("bold", agent.label || agent.name));
-  const providerArgs = getProviderPromptArgs(providerName, agent);
+  const providerArgs = buildProviderArgs(providerName, identityPrompt, antigravityAgent);
   const child = (0, import_node_child_process3.spawn)(providerInfo.command, providerArgs, {
     stdio: "inherit",
     env: runtimeEnv,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashulab/agent-forge",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Give claude/codex/antigravity their own GitHub identity: a bot account, a scoped token minted per run, git attribution to match",
   "license": "MIT",
   "author": "Diego Ghersi <ghersidl@gmail.com>",

package/schema/agents.schema.json

@@ -15,7 +15,8 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "Unique agent id, used with --agent"
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Unique agent id, used with --agent. Lowercase letters, digits, hyphens (also the antigravity custom-agent id)."
           },
           "label": {
             "type": "string",
@@ -43,15 +44,15 @@
           },
           "systemPrompt": {
             "type": "string",
-            "description": "Identity / system prompt injected into the provider and its memory file"
+            "description": "Optional agent-specific system prompt, appended to the identity block agent-forge always injects. Per process: claude --append-system-prompt, codex developer_instructions, antigravity a global custom agent selected with --agent"
           },
           "instructions": {
             "type": "string",
-            "description": "Fallback used as the prompt when systemPrompt is absent"
+            "description": "Fallback for systemPrompt when it is absent; same identity-block + append behavior"
           },
           "identityPrompt": {
             "type": "string",
-            "description": "Fallback used as the prompt when systemPrompt and instructions are absent"
+            "description": "Fallback for systemPrompt and instructions when both are absent; same identity-block + append behavior"
           },
           "repositories": {
             "type": "array",