glab-agent 0.1.0 → 0.2.0

package/README.md

@@ -15,25 +15,38 @@ GitLab-native AI agent orchestration platform. Define coding agents in YAML, man
 
 ## Quick Start
 
+### Prerequisites
+
+- **Node.js >= 20** — `node --version`
+- **glab CLI** — [Install](https://gitlab.com/gitlab-org/cli#installation), then `glab auth login`
+- **Claude CLI** or **Codex CLI** — the AI provider your agent will use
+- **GitLab bot account** (recommended) — a dedicated user account so agent actions appear separately from yours
+
+### Setup
+
 ```bash
-# Install globally
+# 1. Install
 npm install -g glab-agent
 
-# Initialize in your project
+# 2. Initialize in your project
 cd your-project
 glab-agent init my-bot --provider claude
 
-# Set your GitLab token
+# 3. Create a GitLab Personal Access Token for the bot account
+#    → Settings > Access Tokens > scopes: api, read_user, read_repository, write_repository
 echo "GITLAB_TOKEN=glpat-xxx" >> .glab-agent/.env
 
-# Start the agent
-glab-agent start my-bot
+# 4. Verify dependencies
+glab-agent doctor
+
+# 5. Test with a single poll cycle (synchronous, you see output immediately)
+glab-agent run-once my-bot
 
-# Verify it's running
-glab-agent status
+# 6. Start background watcher
+glab-agent start my-bot
 ```
 
-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.
+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. Use `glab-agent watch my-bot` to see what it's doing.
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glab-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Multi-agent GitLab To-Do watcher with YAML-defined agents, skills, and GitLab registry.",
   "license": "MIT",

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

@@ -33,6 +33,24 @@ export interface AgentNotifications {
   webhook_url?: string;
 }
 
+export interface AgentLabelConfig {
+  backlog: string;
+  todo: string;
+  in_progress: string;
+  in_review: string;
+  done: string;
+  error: string;
+}
+
+export const DEFAULT_LABELS: AgentLabelConfig = {
+  backlog: "Backlog",
+  todo: "Todo",
+  in_progress: "In Progress",
+  in_review: "In Review",
+  done: "Done",
+  error: "Error",
+};
+
 export interface AgentDefinition {
   name: string;
   display_name: string;
@@ -52,6 +70,7 @@ export interface AgentDefinition {
   timeout_seconds?: number;
   model?: string;
   notifications: AgentNotifications;
+  labels: AgentLabelConfig;
 }
 
 // ── Loader ───────────────────────────────────────────────────────────────────
@@ -146,6 +165,16 @@ export function parseAgentDefinition(raw: unknown, fileName: string): AgentDefin
     throw new Error(`Invalid provider "${provider}" in ${fileName}. Must be "codex" or "claude".`);
   }
 
+  const rawLabels = (obj.labels ?? {}) as RawValue;
+  const labels: AgentLabelConfig = {
+    backlog: asString(rawLabels.backlog, DEFAULT_LABELS.backlog),
+    todo: asString(rawLabels.todo, DEFAULT_LABELS.todo),
+    in_progress: asString(rawLabels.in_progress, DEFAULT_LABELS.in_progress),
+    in_review: asString(rawLabels.in_review, DEFAULT_LABELS.in_review),
+    done: asString(rawLabels.done, DEFAULT_LABELS.done),
+    error: asString(rawLabels.error, DEFAULT_LABELS.error),
+  };
+
   return {
     name,
     display_name: asString(obj.display_name, name),
@@ -163,7 +192,8 @@ export function parseAgentDefinition(raw: unknown, fileName: string): AgentDefin
       ? obj.timeout_seconds
       : undefined,
     model: typeof obj.model === "string" ? obj.model : undefined,
-    notifications: parseNotifications(obj.notifications)
+    notifications: parseNotifications(obj.notifications),
+    labels,
   };
 }
 

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

@@ -9,6 +9,8 @@ import type { GitlabIssue } from "./gitlab-glab-client.js";
 import type { AgentProvider } from "./agent-provider.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
 import type { Logger } from "./logger.js";
+import { DEFAULT_LABELS } from "./agent-config.js";
+import type { AgentLabelConfig } from "./agent-config.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -24,6 +26,8 @@ export interface AgentRunContext {
 
 export interface AgentRunner {
   run(issue: GitlabIssue, worktree: WorktreeInfo, context?: AgentRunContext): Promise<AgentRunResult>;
+  /** Run a lightweight contextual reply — no worktree, read-only. Optional: falls back to full_work if absent. */
+  runContextual?(issue: GitlabIssue, todoBody: string, context?: AgentRunContext): Promise<AgentRunResult>;
 }
 
 export interface AgentRunnerOptions {
@@ -67,12 +71,53 @@ export interface AgentPromptContext {
   preamble?: string;
   append?: string;
   templatePath?: string;
+  labels?: AgentLabelConfig;
+}
+
+export interface ContextualPromptContext {
+  issueIid: number;
+  issueTitle: string;
+  gitlabHost: string;
+  gitlabProjectId: number;
+  todoBody: string;
+}
+
+/**
+ * Build a lightweight read-only prompt for contextual replies (NT-4).
+ * The agent answers questions and posts a note but does NOT modify code.
+ */
+export function buildContextualPrompt(ctx: ContextualPromptContext): string {
+  const p = ctx.gitlabProjectId;
+  return [
+    "你是项目团队成员（AI agent），收到了一个 @mention 需要回复。",
+    "",
+    "## 任务",
+    `Issue #${ctx.issueIid}: ${truncate(ctx.issueTitle, 200)}`,
+    `@mention 内容: ${ctx.todoBody || "(空)"}`,
+    "",
+    "## GitLab 环境",
+    `- Host: ${ctx.gitlabHost} | Project ID: ${p}`,
+    "- GITLAB_TOKEN 和 GITLAB_HOST 已配置，可直接使用 glab 命令。",
+    "",
+    "## 指令",
+    `1. 读取 issue 详情: glab api projects/${p}/issues/${ctx.issueIid}`,
+    `   读评论: glab api projects/${p}/issues/${ctx.issueIid}/notes`,
+    "2. 阅读项目代码和文档来回答问题。",
+    `3. 在 issue 上发评论回复: glab api --method POST projects/${p}/issues/${ctx.issueIid}/notes --raw-field "body=<回复>"`,
+    "4. **不要修改任何代码文件**。如果需要代码修改，在回复中建议创建新 issue。",
+    "5. 像团队成员一样沟通，自然、简洁、有判断力。",
+    "6. 不要暴露内部实现细节（worktree 路径、执行器名称等）。",
+    "",
+    "## 最终输出",
+    "标准输出不超过 3 行的简短总结（不是 GitLab 评论）。"
+  ].join("\n");
 }
 
 export function buildBasePrompt(ctx: AgentPromptContext): string {
   const p = ctx.gitlabProjectId;
   const iid = ctx.issueIid;
   const todoId = ctx.todoId;
+  const labels = ctx.labels ?? DEFAULT_LABELS;
   return [
     "你是这个项目的团队成员（AI agent），被分配处理一个 GitLab 任务。",
     "你在项目的独立工作分支中，可以读代码、读文档、运行命令、操作 GitLab。",
@@ -97,7 +142,9 @@ export function buildBasePrompt(ctx: AgentPromptContext): string {
     `- 读评论: glab api projects/${p}/issues/${iid}/notes`,
     `- 读关联 issue: glab api projects/${p}/issues/${iid}/links`,
     "- 阅读项目代码和文档，理解架构和设计原则。",
-    "- 如果存在 .glab-agent/wiki/index.md，先查阅项目知识库了解已有经验和踩坑记录。",
+    `- 查阅项目 Wiki（如有）: glab api projects/${p}/wikis`,
+    "  - Wiki 是团队共享的知识库，包含踩坑记录、设计决策、常用模式等。",
+    `  - 读具体页面: glab api "projects/${p}/wikis/<slug>"（slug 含 / 时需 URL 编码为 %2F）`,
     "",
     "### 2. 判断并行动",
     "- **明确的技术任务**（bug fix、功能实现、重构、文档）→ 实现它",
@@ -105,9 +152,9 @@ export function buildBasePrompt(ctx: AgentPromptContext): string {
     "- **信息不足** → 在 issue 上提问，不要猜测需求",
     "",
     "### 3. 管理看板状态",
-    `- 开始工作时: glab api --method PUT projects/${p}/issues/${iid} --raw-field "labels=In Progress"`,
-    `- 创建 MR 后: glab api --method PUT projects/${p}/issues/${iid} --raw-field "labels=In Review"`,
-    `- 遇到无法解决的问题: glab api --method PUT projects/${p}/issues/${iid} --raw-field "labels=Error"`,
+    `- 开始工作时: glab api --method PUT projects/${p}/issues/${iid} --raw-field "labels=${labels.in_progress}"`,
+    `- 创建 MR 后: glab api --method PUT projects/${p}/issues/${iid} --raw-field "labels=${labels.in_review}"`,
+    `- 遇到无法解决的问题: glab api --method PUT projects/${p}/issues/${iid} --raw-field "labels=${labels.error}"`,
     todoId ? `- 处理完成后: glab api --method POST todos/${todoId}/mark_as_done` : "",
     "",
     "### 4. 代码交付（仅当决定实现时）",
@@ -125,6 +172,14 @@ export function buildBasePrompt(ctx: AgentPromptContext): string {
     "- **不要**暴露内部实现细节（worktree 路径、执行器名称、PID 等）。",
     "- **不要**输出内部思考过程。",
     "",
+    "### 6. 知识沉淀",
+    "- 如果在工作过程中发现了新的踩坑经验、设计决策或可复用模式，写入项目 Wiki。",
+    `  - 新建页面: glab api --method POST projects/${p}/wikis --raw-field "title=<标题>" --raw-field "content=<Markdown 内容>"`,
+    `  - 更新已有页面: glab api --method PUT "projects/${p}/wikis/<slug>" --raw-field "title=<原标题>" --raw-field "content=<新内容>"（必须传 title，否则目录前缀会丢失）`,
+    "- 推荐分类: gotchas/（踩坑）、patterns/（模式）、decisions/（决策）、runbooks/（操作手册）。",
+    "- 只记录**非显而易见的**经验。不要记录代码里能直接看到的信息。",
+    "- Wiki 标题用 `分类/标题` 格式，如 `gotchas/并发写入文件需要锁`。",
+    "",
     "## 当前环境",
     `- 分支: ${ctx.branch}`,
     "- 工作目录: 项目的独立工作副本",

package/src/local-agent/claude-runner.ts

@@ -12,6 +12,7 @@ import {
   type AgentRunner,
   type AgentRunnerOptions,
   buildAgentPrompt,
+  buildContextualPrompt,
   createOutputPath,
   isSmokeIssue,
   runSmokeTestChecks
@@ -67,6 +68,7 @@ export class ClaudeRunner implements AgentRunner {
       todoId: context?.todoId,
       preamble: this.agentDefinition?.prompt.preamble,
       append: this.agentDefinition?.prompt.append,
+      labels: this.agentDefinition?.labels,
       // skills injected via .claude/skills/*.md files, not in prompt
     });
     const claudeCommand = resolveClaudeCommand(this.env);
@@ -129,6 +131,72 @@ export class ClaudeRunner implements AgentRunner {
       );
     }
   }
+
+  async runContextual(issue: GitlabIssue, todoBody: string, context?: AgentRunContext): Promise<AgentRunResult> {
+    const signal = context?.signal;
+    const outputPath = await createOutputPath("claude-contextual", issue.iid);
+
+    const prompt = buildContextualPrompt({
+      issueIid: issue.iid,
+      issueTitle: issue.title,
+      gitlabHost: this.gitlabHost,
+      gitlabProjectId: this.gitlabProjectId,
+      todoBody,
+    });
+    const claudeCommand = resolveClaudeCommand(this.env);
+
+    this.logger.info(`Contextual reply: ${claudeCommand} -p ... cwd=${this.repoPath || process.cwd()}`);
+    this.logger.info(`Prompt (${prompt.length} chars): contextual issue #${issue.iid} "${issue.title}"`);
+
+    const timeoutMs = this.timeoutSeconds ? this.timeoutSeconds * 1000 : 0;
+
+    try {
+      const args = ["-p", "--output-format", "text", "--permission-mode", "bypassPermissions"];
+      if (this.agentDefinition?.model) {
+        args.push("--model", this.agentDefinition.model);
+      }
+      args.push(prompt);
+
+      const { stdout } = await this.execFileImpl(
+        claudeCommand,
+        args,
+        {
+          cwd: this.repoPath || process.cwd(),
+          encoding: "utf8",
+          maxBuffer: 10 * 1024 * 1024,
+          env: this.env,
+          ...(timeoutMs > 0 ? { timeout: timeoutMs, killSignal: "SIGTERM" } : {}),
+          ...(signal ? { signal } : {})
+        }
+      );
+
+      const summary = truncate(compactText(stdout || "Contextual reply sent."), 600);
+      this.logger.info(`Contextual reply finished. Output: ${outputPath}`);
+      await writeFile(outputPath, summary, "utf8");
+
+      return { summary, outputPath };
+    } catch (error) {
+      const execError = error as { stdout?: string; stderr?: string; message?: string; killed?: boolean };
+      const isTimeout = execError.killed === true && timeoutMs > 0;
+      const summary = isTimeout
+        ? `Timed out after ${this.timeoutSeconds}s`
+        : truncate(
+            compactText(execError.stdout || execError.stderr || execError.message || "Contextual reply failed."),
+            600
+          );
+      if (isTimeout) {
+        this.logger.error(`Contextual reply timed out after ${this.timeoutSeconds}s.`);
+      } else {
+        this.logger.error(`Contextual reply failed. stderr: ${execError.stderr?.slice(0, 300) ?? "(none)"}`);
+      }
+      await writeFile(outputPath, summary, "utf8");
+      throw new AgentRunnerError(
+        isTimeout ? `Claude Code timed out after ${this.timeoutSeconds}s.` : "Contextual reply failed.",
+        summary,
+        outputPath
+      );
+    }
+  }
 }
 
 export function resolveClaudeCommand(env: NodeJS.ProcessEnv = process.env): string {