@ashulab/agent-forge 0.3.0 → 0.5.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
-- writes the agent's `systemPrompt` into the provider's startup memory file (`CLAUDE.md` / `AGENTS.md`) so subagents inherit the identity
+- 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.
 
@@ -60,9 +60,10 @@ The shape, for reference — the `"$schema"` line points at the published schema
 }
 ```
 
-- The **installation id is not stored** — it is resolved on each run, in order: the owner of the repo you launch in, then `account`, then the App's sole installation. So the same agent works across every org the App is installed on, and it survives an uninstall/reinstall (which rotates the id).
-- Add `"account": "<org-or-user login>"` only when you run outside a matching repo and the App has more than one installation.
-- `installationId` is still accepted as an explicit override — set it to pin a specific id or skip the lookup (offline, or in a git credential helper).
+- The **installation id is not stored** — it is resolved on each run, in order: the owner of the repo you launch in, then the App's sole installation. So the same agent works across every org the App is installed on, and it survives an uninstall/reinstall (which rotates the id).
+- An App installed on more than one account only resolves when you launch from inside a repo it covers — that repo picks the installation.
+- `installationId` is accepted as an explicit override — set it to pin a specific id or skip the lookup (offline, or in a git credential helper).
+- One agent, many accounts: a **private** GitHub App only installs on the account that owns it. To run the agent on both a personal account and an org, make the App public or use one App per account — see [docs/github-app.md](docs/github-app.md).
 - `botId` is optional. When omitted it is resolved from the GitHub API using `botName` so the git author email links commits to the bot. Set it explicitly only to skip that lookup (e.g. offline).
 - Do not put provider-specific config here — providers are auto-detected from PATH.
 
@@ -93,17 +94,19 @@ On launch, `agent-forge` prints the scope GitHub actually granted (`scope` row i
 
 You need a GitHub App first — its **App ID**, a **private key**, and an **installation**. If you don't have one yet, follow [docs/github-app.md](docs/github-app.md).
 
+Running `agent-forge` with no agents configured offers to run the wizard for you.
+
 ### Guided (recommended)
 
 ```bash
 agent-forge add
 ```
 
-You provide the **GitHub App ID** and the **path to its private key**. The wizard derives the rest from the GitHub API — slug (`botName`), bot user id, and the account (asked only when the App is installed on more than one) — asks for a label and an optional system prompt, mints a test token to confirm it works, and writes the entry. It writes to the resolved config path — the global registry (`~/.config/agent-forge/agents.json`) unless `$AGENT_FORGE_CONFIG` or an existing `./agents.json` redirects it.
+You provide the **GitHub App ID** and the **path to its private key**. The wizard derives the rest from the GitHub API — slug (`botName`), bot user id — asks for a label and an optional system prompt, mints a test token to confirm it works, and writes the entry. It writes to the resolved config path — the global registry (`~/.config/agent-forge/agents.json`) unless `$AGENT_FORGE_CONFIG` or an existing `./agents.json` redirects it.
 
 ### Manual
 
-Copy one agent object inside the `agents` array and set unique values for `name`, `label`, `appId`, `botName`, `privateKeyPath` — plus `account` if the App has more than one installation. Make sure the private key file exists and is readable.
+Copy one agent object inside the `agents` array and set unique values for `name`, `label`, `appId`, `botName`, `privateKeyPath`. Make sure the private key file exists and is readable.
 
 ## Launch
 
@@ -113,13 +116,26 @@ Interactive:
 agent-forge
 ```
 
-Direct flags (passing both skips all prompts; passing one pre-fills it):
+Direct flags (passing both skips the menus; passing one pre-fills it, the other is prompted — or auto-picked when only one agent or provider is available):
 
 ```bash
 agent-forge --agent ops-agent --provider claude
 agent-forge --agent review-agent --provider codex
 ```
 
+Before launching, it prints a summary:
+
+```
+│  provider  claude
+│  identity  ops-agent[bot]
+│  account   AshuLab            ← which account the token is for
+│  repo      AshuLab/app        ← the repo you're in (drives account)
+│  scope     write: contents, issues, pull_requests  ·  +4 read
+│  expires   ~59m               ← installation tokens last ~1h
+```
+
+(The `antigravity` provider adds an `agent` row showing the `--agent` id and the custom-agent file it wrote.)
+
 Other commands:
 
 ```bash
@@ -130,10 +146,11 @@ agent-forge --help
 
 ### Provider-specific prompt behavior
 
-- `claude`: passed via `--append-system-prompt` (lands in the real system prompt)
-- `codex` / `antigravity` (`agy`): no CLI flag — identity comes from `AGENTS.md` only (`agy --prompt` is headless `--print`; a codex positional arg is a fake first user turn)
+The identity prompt (identity block + the agent's optional `systemPrompt`) is injected per process — no repo file is touched:
 
-The launcher also writes `systemPrompt` into the provider's startup memory file in the working directory (`CLAUDE.md` for claude, `AGENTS.md` for codex and antigravity), inside a managed `agent-forge:identity` block. This keeps the identity in place for subagents the provider spawns, not just its main thread. The block is rewritten on each run and safe to keep in version control.
+- `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 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}"`);
     }
@@ -5377,19 +5382,9 @@ function pickInstallation(installations, agent) {
   if (installations.length === 0) {
     throw new Error(`GitHub App ${agent.appId} has no installations. Install it on an account or org first.`);
   }
-  if (agent.account) {
-    const want = String(agent.account).toLowerCase();
-    const match = installations.find((item) => item.account.toLowerCase() === want);
-    if (!match) {
-      throw new Error(
-        `GitHub App ${agent.appId} is not installed on "${agent.account}". Installed on: ${installations.map((item) => item.account).join(", ")}.`
-      );
-    }
-    return match.id;
-  }
   if (installations.length === 1) return installations[0].id;
   throw new Error(
-    `GitHub App ${agent.appId} is installed on ${installations.length} accounts (${installations.map((item) => item.account).join(", ")}). Run inside a repo under one of them, or add "account" to agent "${agent.name}".`
+    `GitHub App ${agent.appId} is installed on ${installations.length} accounts (${installations.map((item) => item.account).join(", ")}). Launch from inside a repo under one of them.`
   );
 }
 function parseGithubRemote(url) {
@@ -5479,44 +5474,83 @@ 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 [];
-  }
-  return providerName === "claude" ? ["--append-system-prompt", prompt] : [];
+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 = { claude: "CLAUDE.md", codex: "AGENTS.md", 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));
 }
-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;
+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, description, prompt) {
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${JSON.stringify(description)}`,
+    "mainAgent: true",
+    MARKER,
+    "---",
+    "",
+    "# Identity",
+    "",
+    prompt.trimEnd(),
+    ""
+  ].join("\n");
+}
+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, agent.label || "GitHub App identity managed by agent-forge", 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
@@ -5542,7 +5576,7 @@ var import_node_util3 = require("node:util");
 // package.json
 var package_default = {
   name: "@ashulab/agent-forge",
-  version: "0.3.0",
+  version: "0.5.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>",
@@ -5664,19 +5698,25 @@ async function addAgentWizard({ embedded = false } = {}) {
   if (meta.installations.length === 0) {
     throw new Error("This App has no installations. Install it on an account or org first.");
   }
-  let account;
-  if (meta.installations.length === 1) {
-    note(`${meta.installations[0].account} \u2014 resolved automatically each run`, "Installation");
-  } else {
-    account = keep(
-      await select({
-        message: "Which account is this agent for?",
-        options: meta.installations.map((i2) => ({ value: i2.account, label: `${i2.account} (${i2.id})` }))
-      })
-    );
-  }
-  const name = (keep(await text({ message: "Agent name", placeholder: meta.slug, defaultValue: meta.slug })) || meta.slug).trim();
+  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,
+    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,
@@ -5684,7 +5724,6 @@ async function addAgentWizard({ embedded = false } = {}) {
     appId,
     botName: meta.slug,
     privateKeyPath,
-    ...account ? { account } : {},
     ...systemPrompt ? { systemPrompt } : {}
   };
   const check = spinner();
@@ -5805,7 +5844,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,
@@ -5826,11 +5869,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.3.0",
+  "version": "0.5.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",
@@ -25,13 +26,9 @@
             "type": "string",
             "description": "GitHub App ID (numeric, stored as a string)"
           },
-          "account": {
-            "type": "string",
-            "description": "Account/org login where the App is installed. Fallback for installation-id resolution when you run outside a matching repo. Needed only when the App has more than one installation. Resolution order: repo owner, then account, then the sole installation."
-          },
           "installationId": {
             "type": "string",
-            "description": "Optional override. Normally the installation id is resolved (repo owner, then account, then the sole installation). Set this to pin a specific id or skip the lookup (offline, or in a git credential helper)."
+            "description": "Optional override. Normally the installation id is resolved (repo owner, then the App's sole installation). Set this to pin a specific id or skip the lookup (offline, or in a git credential helper)."
           },
           "botName": {
             "type": "string",
@@ -47,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",