glab-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 glab-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# glab-agent
+
+GitLab-native AI agent orchestration platform. Define coding agents in YAML, manage them through GitLab's native interface, and enforce team standards through shared Skills.
+
+## Why Local Agent?
+
+| | Cloud Agents (Devin, Jules) | **glab-agent** |
+|---|---|---|
+| Code location | Uploaded to cloud sandbox | **Stays on your GitLab** |
+| Data security | Code passes through third-party servers | **Code never leaves your network** |
+| Customization | Platform defaults | **YAML-defined agents, skills, triggers** |
+| Team standards | Each person configures individually | **Shared Skills enforce team conventions** |
+| Provider lock-in | Single model | **Claude, Codex — switch with one line** (Gemini planned) |
+| Observability | Platform UI | **Reuses your existing GitLab boards** |
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g glab-agent
+
+# Initialize in your project
+cd your-project
+glab-agent init my-bot --provider claude
+
+# Set your GitLab token
+echo "GITLAB_TOKEN=glpat-xxx" >> .glab-agent/.env
+
+# Start the agent
+glab-agent start my-bot
+
+# Verify it's running
+glab-agent status
+```
+
+Then go to any GitLab issue and type `@your-bot-username` — the agent will pick it up, write code, run tests, and create a merge request.
+
+## How It Works
+
+```
+┌─────────── GitLab ───────────┐
+│  Issues → @mention → Todos   │
+└──────────────┬───────────────┘
+               │ poll
+        ┌──────▼──────┐
+        │   Watcher   │  Filter by triggers, manage labels
+        └──────┬──────┘
+        ┌──────▼──────┐
+        │  AI Agent   │  Read issue → Code → Test → Push → Create MR
+        │ (Claude/    │
+        │  Codex)     │
+        └─────────────┘
+```
+
+**Watcher** polls GitLab for new todos, filters by your configured triggers, creates an isolated git worktree, and launches the AI agent. The **Agent** autonomously reads the issue, writes code, runs tests, commits, pushes, and creates a merge request.
+
+## Agent Definition (YAML)
+
+```yaml
+# .glab-agent/agents/backend-bot.yaml
+name: backend-bot
+provider: claude
+gitlab:
+  token_env: GITLAB_TOKEN
+prompt:
+  preamble: "You are a backend engineer focused on API correctness and test coverage."
+triggers:
+  labels: [backend]
+  actions: [mentioned]
+skills:
+  - test-before-commit    # Reference a shared skill by name
+  - security-scan
+poll_interval_seconds: 60
+```
+
+## Shared Skills
+
+Skills are reusable prompt fragments in SKILL.md format (YAML frontmatter + markdown body). Store them in `.glab-agent/skills/`:
+
+```markdown
+<!-- .glab-agent/skills/test-before-commit.md -->
+---
+name: test-before-commit
+description: Run tests before committing
+---
+
+After modifying code, run tests to ensure they pass.
+If tests fail, fix the issues before committing.
+```
+
+Import skills from GitHub (including [Anthropic's official skill library](https://github.com/anthropics/skills)):
+
+```bash
+glab-agent skills                          # List all shared skills
+glab-agent skills import anthropics/skills  # Import from GitHub
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `glab-agent init [name]` | Initialize project and optionally create an agent |
+| `glab-agent list` | List all agent definitions |
+| `glab-agent start <name>` | Start agent as background watcher |
+| `glab-agent stop <name>` | Stop agent |
+| `glab-agent status [name]` | Show agent status with heartbeat |
+| `glab-agent watch <name>` | Real-time agent monitoring |
+| `glab-agent run-once <name>` | Run single watcher cycle |
+| `glab-agent cancel <name>` | Cancel current task |
+| `glab-agent retry <name> <iid>` | Retry a failed issue |
+| `glab-agent why <iid>` | Diagnose why an issue wasn't picked up |
+| `glab-agent history <name>` | Show execution history |
+| `glab-agent skills` | List shared skills |
+| `glab-agent gc <name>` | Clean up old worktrees |
+| `glab-agent doctor` | Check prerequisites |
+
+All commands support `--project <dir>` to target a different directory.
+
+## GitLab as Control Plane
+
+No extra dashboards needed. glab-agent maps to GitLab's native features:
+
+- **User Status** — Agent shows as 🟢 Ready / 🔧 Working / 🔴 Offline in team member list
+- **Issue Board** — Agent work appears as cards moving through Backlog → In Progress → In Review → Done
+- **Labels** — Status machine: `In Progress`, `In Review`, `Done`, `Error`
+- **@mention** — Trigger agents just like you'd assign a colleague
+- **User Bio** — Agent's skills and instructions visible on its GitLab profile
+
+## Reliability
+
+- **API retry** — Exponential backoff (1s/2s/4s) for transient failures
+- **Circuit breaker** — Stops polling after 5 consecutive failures, backs off up to 5 minutes
+- **Atomic state writes** — Write-to-temp + rename prevents corruption on crash
+- **Heartbeat monitoring** — Detects stale watchers via `glab-agent status`
+- **Graceful shutdown** — SIGTERM updates GitLab status before exit
+
+## Observability
+
+- **Structured logging** — JSON Lines format via `GITLAB_AGENT_LOG_FORMAT=json`
+- **Metrics** — Append-only JSONL per agent (`.glab-agent/metrics/`)
+- **Heartbeat** — Cycle count and last error in `.glab-agent/heartbeat/`
+
+## Requirements
+
+- Node.js >= 20
+- [glab](https://gitlab.com/gitlab-org/cli) — GitLab CLI
+- [claude](https://claude.ai/code) or [codex](https://openai.com/codex) — AI coding CLI
+- A GitLab personal access token with `api` scope
+
+## License
+
+[MIT](LICENSE)

package/bin/glab-agent.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { resolve, dirname } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const installDir = resolve(dirname(__filename), "..");
+const tsxPath = resolve(installDir, "node_modules", ".bin", "tsx");
+const cliPath = resolve(installDir, "src", "local-agent", "cli.ts");
+
+try {
+  execFileSync(tsxPath, [cliPath, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env: process.env
+  });
+} catch (error) {
+  process.exit(error?.status ?? 1);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "glab-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Multi-agent GitLab To-Do watcher with YAML-defined agents, skills, and GitLab registry.",
+  "license": "MIT",
+  "author": "glab-agent contributors",
+  "keywords": [
+    "gitlab",
+    "agent",
+    "ai",
+    "coding-agent",
+    "claude",
+    "codex",
+    "automation",
+    "devops",
+    "cli"
+  ],
+  "packageManager": "pnpm@9.15.9",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "glab-agent": "./bin/glab-agent.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "agent": "tsx src/local-agent/cli.ts",
+    "smoke-test": "zsh scripts/smoke-test.sh",
+    "smoke-test:full": "zsh scripts/smoke-test.sh --wait-finish",
+    "docs-lint": "zsh scripts/docs-lint.sh",
+    "check": "zsh scripts/ci.sh",
+    "check:full": "zsh scripts/ci.sh --full",
+    "deploy": "zsh scripts/cd.sh",
+    "deploy:fast": "zsh scripts/cd.sh --skip-ci",
+    "gitlab:up": "docker compose -f docker/docker-compose.gitlab.yml up -d",
+    "gitlab:down": "docker compose -f docker/docker-compose.gitlab.yml down",
+    "gitlab:seed": "bash docker/seed-gitlab.sh",
+    "gitlab:reset": "docker compose -f docker/docker-compose.gitlab.yml down -v && rm -rf docker/data docker/ssh .env.test.local .test-repo && echo 'Reset complete'",
+    "gitlab:setup": "pnpm gitlab:up && pnpm gitlab:seed"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.30",
+    "typescript": "^5.8.3",
+    "vitest": "^1.6.1"
+  },
+  "dependencies": {
+    "tsx": "^4.19.3",
+    "yaml": "^2.8.3"
+  }
+}

package/src/local-agent/agent-config.ts

@@ -0,0 +1,315 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseSkillMd } from "./skill-parse.js";
+
+// ── Agent Definition Schema ──────────────────────────────────────────────────
+
+export interface AgentSkill {
+  name: string;
+  description: string;
+  prompt_inject: string;
+}
+
+export interface AgentTriggers {
+  actions: string[];
+  labels: string[];
+  exclude_labels: string[];
+}
+
+export interface AgentPromptConfig {
+  preamble?: string;
+  append?: string;
+  template?: string;
+}
+
+export interface AgentGitlabConfig {
+  host?: string;
+  project_id?: number;
+  token_env: string;
+}
+
+export interface AgentNotifications {
+  webhook_url?: string;
+}
+
+export interface AgentDefinition {
+  name: string;
+  display_name: string;
+  description: string;
+
+  gitlab: AgentGitlabConfig;
+  provider: "codex" | "claude";
+  repo_path?: string;
+
+  prompt: AgentPromptConfig;
+  triggers: AgentTriggers;
+  skills: AgentSkill[];
+  skill_refs: string[];
+
+  poll_interval_seconds: number;
+  concurrency: number;
+  timeout_seconds?: number;
+  model?: string;
+  notifications: AgentNotifications;
+}
+
+// ── Loader ───────────────────────────────────────────────────────────────────
+
+type RawValue = Record<string, unknown>;
+
+function asString(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v): v is string => typeof v === "string");
+}
+
+function parseSkills(raw: unknown): AgentSkill[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((item): item is RawValue => typeof item === "object" && item !== null)
+    .map((item) => ({
+      name: asString(item.name, "unnamed"),
+      description: asString(item.description, ""),
+      prompt_inject: asString(item.prompt_inject, "")
+    }))
+    .filter((s) => s.prompt_inject.length > 0);
+}
+
+function parseSkillRefs(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((item): item is string => typeof item === "string");
+}
+
+function parseTriggers(raw: unknown): AgentTriggers {
+  if (typeof raw !== "object" || raw === null) {
+    return { actions: ["mentioned", "directly_addressed"], labels: [], exclude_labels: [] };
+  }
+  const obj = raw as RawValue;
+  return {
+    actions: asStringArray(obj.actions).length > 0
+      ? asStringArray(obj.actions)
+      : ["mentioned", "directly_addressed"],
+    labels: asStringArray(obj.labels),
+    exclude_labels: asStringArray(obj.exclude_labels)
+  };
+}
+
+function parseNotifications(raw: unknown): AgentNotifications {
+  if (typeof raw !== "object" || raw === null) return {};
+  const obj = raw as RawValue;
+  return {
+    webhook_url: typeof obj.webhook_url === "string" ? obj.webhook_url : undefined
+  };
+}
+
+function parsePromptConfig(raw: unknown): AgentPromptConfig {
+  if (typeof raw !== "object" || raw === null) return {};
+  const obj = raw as RawValue;
+  return {
+    preamble: typeof obj.preamble === "string" ? obj.preamble : undefined,
+    append: typeof obj.append === "string" ? obj.append : undefined,
+    template: typeof obj.template === "string" ? obj.template : undefined
+  };
+}
+
+function parseGitlabConfig(raw: unknown): AgentGitlabConfig {
+  if (typeof raw !== "object" || raw === null) {
+    return { token_env: "GITLAB_TOKEN" };
+  }
+  const obj = raw as RawValue;
+  return {
+    host: typeof obj.host === "string" ? obj.host : undefined,
+    project_id: typeof obj.project_id === "number" ? obj.project_id : undefined,
+    token_env: asString(obj.token_env, "GITLAB_TOKEN")
+  };
+}
+
+export function parseAgentDefinition(raw: unknown, fileName: string): AgentDefinition {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error(`Invalid agent definition in ${fileName}: expected an object.`);
+  }
+  const obj = raw as RawValue;
+  const nameFromFile = path.basename(fileName, path.extname(fileName));
+  const name = asString(obj.name, nameFromFile);
+
+  const provider = asString(obj.provider, "claude");
+  if (provider !== "codex" && provider !== "claude") {
+    throw new Error(`Invalid provider "${provider}" in ${fileName}. Must be "codex" or "claude".`);
+  }
+
+  return {
+    name,
+    display_name: asString(obj.display_name, name),
+    description: asString(obj.description, ""),
+    gitlab: parseGitlabConfig(obj.gitlab),
+    provider,
+    repo_path: typeof obj.repo_path === "string" ? obj.repo_path : undefined,
+    prompt: parsePromptConfig(obj.prompt),
+    triggers: parseTriggers(obj.triggers),
+    skills: parseSkills(obj.skills),
+    skill_refs: parseSkillRefs(obj.skills),
+    poll_interval_seconds: asNumber(obj.poll_interval_seconds, 60),
+    concurrency: asNumber(obj.concurrency, 1),
+    timeout_seconds: typeof obj.timeout_seconds === "number" && obj.timeout_seconds > 0
+      ? obj.timeout_seconds
+      : undefined,
+    model: typeof obj.model === "string" ? obj.model : undefined,
+    notifications: parseNotifications(obj.notifications)
+  };
+}
+
+export async function loadAgentDefinition(yamlPath: string): Promise<AgentDefinition> {
+  const content = await readFile(yamlPath, "utf8");
+  const raw = parseYaml(content);
+  return parseAgentDefinition(raw, path.basename(yamlPath));
+}
+
+export async function loadAgentByName(agentsDir: string, name: string): Promise<AgentDefinition> {
+  const yamlPath = path.join(agentsDir, `${name}.yaml`);
+  return loadAgentDefinition(yamlPath);
+}
+
+export async function discoverAgents(agentsDir: string): Promise<AgentDefinition[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(agentsDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+
+  const yamlFiles = entries
+    .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+    .sort();
+
+  const definitions: AgentDefinition[] = [];
+  for (const file of yamlFiles) {
+    const def = await loadAgentDefinition(path.join(agentsDir, file));
+    // Skip files that are not agent definitions (e.g., openai.yaml interface-only)
+    if (def.description || def.skills.length > 0 || def.prompt.preamble || def.prompt.template) {
+      definitions.push(def);
+    }
+  }
+  return definitions;
+}
+
+const AGENT_DIR = ".glab-agent";
+
+export function agentBaseDir(repoPath: string): string {
+  return path.join(repoPath, AGENT_DIR);
+}
+
+export function agentAgentsDir(repoPath: string): string {
+  return path.join(repoPath, AGENT_DIR, "agents");
+}
+
+export function agentEnvPath(repoPath: string): string {
+  return path.join(repoPath, AGENT_DIR, ".env");
+}
+
+export function agentStateDir(repoPath: string): string {
+  return path.join(repoPath, AGENT_DIR, "state");
+}
+
+export function agentStatePath(repoPath: string, agentName: string): string {
+  return path.join(agentStateDir(repoPath), `${agentName}.json`);
+}
+
+export function agentLogPath(repoPath: string, agentName: string): string {
+  return path.join(repoPath, AGENT_DIR, "logs", agentName);
+}
+
+export function agentWorktreeRoot(repoPath: string, agentName: string): string {
+  return path.join(repoPath, AGENT_DIR, "worktrees", agentName);
+}
+
+export function agentPidPath(repoPath: string, agentName: string): string {
+  return path.join(repoPath, AGENT_DIR, "pid", `${agentName}.pid`);
+}
+
+export function agentHeartbeatPath(repoPath: string, agentName: string): string {
+  return path.join(repoPath, AGENT_DIR, "heartbeat", `${agentName}.json`);
+}
+
+export function agentSkillsDir(repoPath: string): string {
+  return path.join(repoPath, AGENT_DIR, "skills");
+}
+
+export async function loadSharedSkill(skillsDir: string, name: string): Promise<AgentSkill> {
+  // Try YAML first, then fall back to .md (SKILL.md format)
+  let content: string;
+  let format: "yaml" | "md";
+  try {
+    content = await readFile(path.join(skillsDir, `${name}.yaml`), "utf8");
+    format = "yaml";
+  } catch (yamlErr) {
+    if ((yamlErr as NodeJS.ErrnoException).code !== "ENOENT") throw yamlErr;
+    try {
+      content = await readFile(path.join(skillsDir, `${name}.md`), "utf8");
+      format = "md";
+    } catch (mdErr) {
+      if ((mdErr as NodeJS.ErrnoException).code !== "ENOENT") throw mdErr;
+      throw new Error(`Skill "${name}" not found as .yaml or .md in ${skillsDir}`);
+    }
+  }
+
+  if (format === "md") {
+    const parsed = parseSkillMd(content);
+    if (!parsed) throw new Error(`Invalid SKILL.md format for "${name}"`);
+    return parsed;
+  }
+
+  const raw = parseYaml(content);
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error(`Invalid skill definition in ${name}.yaml`);
+  }
+  const obj = raw as Record<string, unknown>;
+  return {
+    name: asString(obj.name, name),
+    description: asString(obj.description, ""),
+    prompt_inject: asString(obj.prompt_inject, "")
+  };
+}
+
+export async function discoverSharedSkills(skillsDir: string): Promise<AgentSkill[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(skillsDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  const yamlFiles = entries.filter(f => f.endsWith(".yaml") || f.endsWith(".yml") || f.endsWith(".md")).sort();
+  const skills: AgentSkill[] = [];
+  for (const file of yamlFiles) {
+    const skill = await loadSharedSkill(skillsDir, path.basename(file, path.extname(file)));
+    if (skill.prompt_inject.length > 0) {
+      skills.push(skill);
+    }
+  }
+  return skills;
+}
+
+export async function resolveSkills(def: AgentDefinition, skillsDir: string): Promise<AgentSkill[]> {
+  const resolved: AgentSkill[] = [...def.skills];
+  for (const ref of def.skill_refs) {
+    try {
+      const shared = await loadSharedSkill(skillsDir, ref);
+      if (!resolved.some(s => s.name === shared.name)) {
+        resolved.push(shared);
+      }
+    } catch {
+      // Shared skill not found, skip silently
+    }
+  }
+  return resolved;
+}

package/src/local-agent/agent-provider.ts

@@ -0,0 +1,59 @@
+export type AgentProvider = "codex" | "claude";
+
+export type AgentProviderSource = "env_override" | "environment_default";
+
+export interface ResolvedAgentProvider {
+  provider: AgentProvider;
+  source: AgentProviderSource;
+}
+
+function normalizeEnvValue(value?: string): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function isClaudeCodeEnvironment(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(
+    normalizeEnvValue(env.CLAUDE_CODE_ENTRYPOINT) ??
+      normalizeEnvValue(env.CLAUDE_CODE_REMOTE) ??
+      normalizeEnvValue(env.CLAUDE_CODE_ENVIRONMENT_KIND)
+  );
+}
+
+export function resolveAgentProvider(env: NodeJS.ProcessEnv = process.env): ResolvedAgentProvider {
+  const explicit = normalizeEnvValue(env.AGENT_PROVIDER);
+
+  if (explicit) {
+    if (explicit === "codex" || explicit === "claude") {
+      return {
+        provider: explicit,
+        source: "env_override"
+      };
+    }
+
+    throw new Error(`AGENT_PROVIDER must be one of: codex, claude. Received: ${explicit}`);
+  }
+
+  return {
+    provider: isClaudeCodeEnvironment(env) ? "claude" : "codex",
+    source: "environment_default"
+  };
+}
+
+export function getAgentDisplayName(provider: AgentProvider): string {
+  return provider === "claude" ? "Claude Code" : "Codex";
+}
+
+export function getAgentNotePrefixes(provider: AgentProvider): {
+  accepted: string;
+  completed: string;
+  failed: string;
+} {
+  const displayName = getAgentDisplayName(provider);
+
+  return {
+    accepted: `${displayName} 已接单。`,
+    completed: `${displayName} 已完成。`,
+    failed: `${displayName} 执行失败。`
+  };
+}