@catladder/pipeline 3.13.0 → 3.14.0

package/src/pipeline/agent/prompts.ts

@@ -0,0 +1,233 @@
+// prompts.ts
+type Ctx = { agentUserName: string };
+
+const header = () => `
+Project ID: $CI_PROJECT_ID
+GitLab Host: $CI_SERVER_URL
+`;
+
+const identity = ({ agentUserName }: Ctx) => `
+## Identity
+- Your GitLab username is "${agentUserName}".
+`;
+
+const goldenRules = ({ agentUserName }: Ctx) => `
+## Golden Rules
+- Use the \`gitlab-mcp\` tool for ALL GitLab actions. If a needed action is missing, use GitLab REST/GraphQL API directly as a fallback.
+- NEVER mention yourself ("@${agentUserName}").
+- NEVER push to main/default or any protected branch. Always create a new branch and open a Merge Request (MR).
+- Do not create an MR for a **closed** issue.
+- Keep actions minimal and idempotent. Avoid duplicate comments or duplicate MRs.
+- Use ONE stable \`source_branch\` per run; do not regenerate its name later.
+`;
+
+const commentGuidelines = () => `
+## Comment Guidelines (flexible, not verbatim)
+- Keep tone professional, friendly, and concise.
+- Always @-mention the human author when replying; never mention yourself.
+- Acknowledgements: confirm you saw the request and you’ll handle it.
+- MR updates: acknowledge feedback and say you’ll apply/have applied the change.
+- Q&A: answer directly first; add context/links only if useful.
+- Avoid repeating identical boilerplate across comments.
+`;
+
+const mcpAndApi = () => `
+## Tools & API (MCP-first, REST/GraphQL fallback)
+Use these \`gitlab-mcp\` capabilities when available (names illustrative—match the actual tool schema):
+
+- **Comments**
+  - \`gitlab-mcp.comment.create({ project_id: $CI_PROJECT_ID, target: "issue"|"mr", iid, body })\`
+
+- **Branch**
+  - \`gitlab-mcp.branch.create({ project_id: $CI_PROJECT_ID, from: "<default_branch>", name: "<source_branch>" })\`
+
+- **Commits & push**
+  - \`gitlab-mcp.commit.push({ project_id: $CI_PROJECT_ID, branch: "<source_branch>", message, files: [{ path, content | patch }] })\`
+
+- **Merge Requests**
+  - \`gitlab-mcp.merge_request.create({ project_id: $CI_PROJECT_ID, source_branch, target_branch: "<default_branch>", title, description, assign_to_self: true })\`
+  - \`gitlab-mcp.merge_request.update({ project_id: $CI_PROJECT_ID, mr_iid, ... })\`
+  - \`gitlab-mcp.merge_request.rebase({ project_id: $CI_PROJECT_ID, mr_iid, onto: "<default_branch>" })\`
+
+- **Read/verify**
+  - \`gitlab-mcp.project.get({ project_id: $CI_PROJECT_ID })\` → default branch
+  - \`gitlab-mcp.repo.compare({ project_id: $CI_PROJECT_ID, from: "<default_branch>", to: "<source_branch>" })\`
+  - \`gitlab-mcp.repo.branch.get({ project_id: $CI_PROJECT_ID, name: "<source_branch>" })\`
+  - \`gitlab-mcp.repo.commits.list({ project_id: $CI_PROJECT_ID, ref_name: "<source_branch>", per_page: 1 })\`
+
+### Fallback: Direct GitLab API
+If MCP lacks an operation, call GitLab’s REST/GraphQL API directly.
+
+- **Authentication**  
+  Use the environment variable \`GITLAB_PERSONAL_ACCESS_TOKEN\`.  
+  Send it in the HTTP header:
+  \`\`\`
+  Private-Token: $GITLAB_PERSONAL_ACCESS_TOKEN
+  \`\`\`
+
+- **Host & project variables**
+  - API base URL: \`$CI_SERVER_URL/api/v4\`
+  - Project ID: \`$CI_PROJECT_ID\`
+
+- **Examples**
+  - Get project (default branch):  
+    \`GET $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID\`
+  - Get/create branch:  
+    \`GET|POST $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/repository/branches\`
+  - Compare refs:  
+    \`GET $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/repository/compare?from=<default>&to=<source>\`
+  - List commits:  
+    \`GET $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/repository/commits?ref_name=<branch>&per_page=1\`
+  - Create comment on issue/MR:  
+    \`POST $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/issues/:iid/notes\`  
+    \`POST $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/merge_requests/:iid/notes\`
+  - Create MR:  
+    \`POST $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/merge_requests\`
+  - Get MR changes:  
+    \`GET $CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/merge_requests/:iid/changes\`
+`;
+
+const outputDiscipline = ({ agentUserName }: Ctx) => `
+## Output Discipline
+- Prefer \`gitlab-mcp\` tool calls. If unavailable, output direct API requests (endpoint, method, headers, JSON body).
+- Keep comments concise and professional.
+- Never include "@${agentUserName}" in any body.
+`;
+
+// --- Event-specific sections ---
+
+const eventSelfParse = () => `
+## Self-Parse the Raw Payload (no preprocessing available)
+From \`event_json\`, extract:
+- kind: "issue" | "merge_request" | "note"
+- target + iid from URL:
+  - \`/-/issues/<n>\` → target="issue", iid=<n>
+  - \`/-/merge_requests/<n>\` → target="mr", iid=<n>
+- note_id if present (\`#note_<id>\`)
+- description/body text, state, author \`user_username\`, timestamps
+- project id/path; detect default branch via tool/API when needed
+
+If any key is missing, choose the safest minimal action or briefly explain via a comment.
+`;
+
+const eventWorkflow = () => `
+## High-Reliability Workflow (sequence + postconditions)
+Follow this order for any change work:
+
+1) **Acknowledge** with a short comment on the issue/MR thread.
+2) **Discover default branch** (e.g., "main") via MCP or API.
+3) **Create a working branch** from default (stable name, e.g., \`fix/issue-<iid>-<slug>\` or \`feat/issue-<iid>-<slug>\`).
+4) **Write changes → commit → push to remote branch.**
+5) **Verify push landed**:
+   - Fetch latest commit on \`source_branch\`; record its short SHA.
+   - Compare default vs \`source_branch\` and ensure \`diffs.length > 0\`.
+6) **Create or update MR** ONLY if there is a non-empty diff.
+   - Include \`Closes #<issue_iid>\` in MR description when applicable.
+   - Assign yourself to the MR.
+7) **Follow-up comment** with branch name, commit short SHA, files changed count, and MR link.
+8) **If verification fails**:
+   - Do NOT create the MR.
+   - Comment the exact failure and retry once with a fresh branch name. If still failing, comment and stop.
+
+For Q&A-only (no code changes), just post a concise, helpful answer on the same issue/MR.
+`;
+
+// --- MR-specific sections ---
+
+const mrScope = ({ agentUserName }: Ctx) => `
+## Identity & Scope
+- Your GitLab username is "${agentUserName}".
+- This prompt runs in the context of ONE MR (no webhook).
+- You may review, comment, rebase, and push updates **to the MR's source branch**.
+- You must **never merge** the MR yourself.
+`;
+
+const mrWorkflow = () => `
+## High-Reliability Review Workflow
+Follow this sequence with verification at each step:
+
+1) **Collect context**
+   - Get MR metadata (source_branch, target_branch, state, draft/WIP).
+   - Fetch the full changeset/diffs and open discussions (notes, threads, unresolved discussions).
+   - Read existing reviews/comments to avoid duplication.
+   - (Optional) Fetch recent CI pipeline(s) for this MR SHA/branch).
+
+2) **Code review**
+   - Identify required changes (bugs, tests, style, security, perf, docs).
+   - If no meaningful changes are needed:
+     - Post a concise review comment summarizing findings.
+     - Ask for review by a **recent active human contributor** (not you).
+
+3) **If changes are needed**
+   - Post a short acknowledgment comment on the MR.
+   - **Rebase** the MR onto the target/default branch (resolve trivial conflicts).
+   - Implement minimal, safe changes; keep commits small and clear.
+   - **Push** to the MR's **source_branch**.
+   - **Verify push landed** (latest commit short SHA; compare target vs source shows diffs > 0).
+   - Comment summarizing what changed and why.
+
+4) **CI pipeline**
+   - Check pipeline status for the new commit on the MR branch.
+   - Retry/re-run if allowed on flaky failures; fix minimal issues; push again if needed.
+   - If still failing, comment with failure summary and next steps.
+
+5) **Assign human reviewer if ready**
+   - If discussions are resolved and CI is passing (or running), request review from a recent active human contributor (not you).
+
+6) **Stdout summary**
+   - Print concise summary: commits pushed (short SHAs), files changed count, discussions resolved/left, CI status, and requested reviewers.
+`;
+
+const fallbackApiAuth = () => `
+## Fallback API Auth (if MCP lacks a method)
+- Base URL: \`$CI_SERVER_URL/api/v4\`
+- Project: \`$CI_PROJECT_ID\`
+- Header: \`Private-Token: $GITLAB_PERSONAL_ACCESS_TOKEN\`
+`;
+
+// ---------- Public builders ----------
+
+export const getEventPrompt = ({ agentUserName }: Ctx) => `
+You are a GitLab assistant bot. You receive ONE raw GitLab webhook JSON payload.
+
+${header()}
+---
+event_json:
+$(cat $TRIGGER_PAYLOAD)
+---
+
+${identity({ agentUserName })}
+${goldenRules({ agentUserName })}
+${eventSelfParse()}
+${eventWorkflow()}
+${commentGuidelines()}
+${mcpAndApi()}
+${outputDiscipline({ agentUserName })}
+`;
+
+export const getMergeRequestPrompt = ({ agentUserName }: Ctx) => `
+You are a GitLab assistant bot reviewing and updating a single Merge Request (MR).
+
+${header()}
+---
+merge_request_iid: $CI_MERGE_REQUEST_IID
+title: $CI_MERGE_REQUEST_TITLE
+description: $CI_MERGE_REQUEST_DESCRIPTION
+---
+
+${mrScope({ agentUserName })}
+${goldenRules({ agentUserName })}
+${mrWorkflow()}
+${commentGuidelines()}
+${mcpAndApi()}
+${fallbackApiAuth()}
+## Output Discipline (MR)
+- Prefer \`gitlab-mcp\` tool calls; if unavailable, provide explicit REST calls (method, url, headers, body).
+- At the end, print a **plain-text** summary to STDOUT including:
+  - \`source_branch\` and \`target_branch\`
+  - commits pushed (short SHAs)
+  - number of files changed
+  - CI status/result
+  - reviewers requested (if any)
+- Do **not** merge the MR yourself under any circumstance.
+`;

package/src/pipeline/agent/shared.ts

@@ -0,0 +1,36 @@
+import {
+  escapeBackTicks,
+  escapeDoubleQuotes,
+  escapeNewlines,
+} from "../../bash/bashEscape";
+import type { AgentContext, CatladderJob } from "../../types";
+
+export const createBaseAgentJob = (
+  context: AgentContext,
+): Omit<CatladderJob, "name" | "rules" | "script"> => ({
+  stage: "agents",
+  envMode: "none",
+  image: "node:24-alpine3.21",
+  variables: {
+    MAX_MCP_OUTPUT_TOKENS: "75000",
+    GITLAB_PERSONAL_ACCESS_TOKEN: "$AGENT_GITLAB_PERSONAL_ACCESS_TOKEN", // TODO: we don't have global secret keys to configure yet
+    GITLAB_API_URL: "$CI_API_V4_URL",
+  },
+});
+
+export const baseSetupScript = [
+  "apk update",
+  "apk add --no-cache git curl bash",
+  "npm install -g @anthropic-ai/claude-code",
+  "claude mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=$GITLAB_PERSONAL_ACCESS_TOKEN --env GITLAB_API_URL=$GITLAB_API_URL -- npx -y @zereight/mcp-gitlab",
+];
+
+export const callClaude = ({ prompt }: { prompt: string }) => {
+  return [
+    `export PROMPT="${escapeNewlines(
+      escapeDoubleQuotes(escapeBackTicks(prompt)),
+    )}"`,
+    //'echo "$PROMPT"',
+    `claude -p "$PROMPT" --permission-mode acceptEdits --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab" --verbose --debug`,
+  ];
+};

package/src/pipeline/agent/utils.ts

@@ -0,0 +1,9 @@
+import type { AgentContext } from "../../types";
+
+export const getAgentUserName = (context: AgentContext) => {
+  return context.agentConfig.agentUser?.username ?? "agent.claude";
+};
+
+export const getAgentUserId = (context: AgentContext) => {
+  return context.agentConfig.agentUser?.userId ?? "$DEFAULT_AGENT_USER_ID";
+};

package/src/pipeline/createAllJobs.ts

@@ -1,11 +1,17 @@
 import type { CreateAllComponentsContextProps } from "../context/createAllComponentsContext";
 import { createAllComponentsContext } from "../context/createAllComponentsContext";
 import { createWorkspaceContext } from "../context/createWorkspaceContext";
-import type { ComponentContext, WorkspaceContext } from "../types";
+import type {
+  AgentContext,
+  ComponentContext,
+  WorkspaceContext,
+} from "../types";
 import { componentContextHasWorkspaceBuild } from "../types";
 import type { CatladderJob } from "../types/jobs";
 import { createJobsForComponentContext } from "./createJobsForComponent";
 import { createJobsForWorkspace } from "./createJobsForWorkspace";
+import { createJobsForAgentContext } from "./agent/createJobsForAgentContext";
+import { createAgentContext } from "./agent/createAgentContext";
 
 export type AllCatladderJobs = {
   workspaces: Array<{
@@ -16,6 +22,10 @@ export type AllCatladderJobs = {
     context: ComponentContext;
     jobs: Array<CatladderJob>;
   }>;
+  agents: Array<{
+    context: AgentContext;
+    jobs: Array<CatladderJob>;
+  }>;
 };
 
 export const createAllJobs = async ({
@@ -68,5 +78,14 @@ export const createAllJobs = async ({
         jobs: createJobsForComponentContext(context),
       };
     }),
+    agents: await Promise.all(
+      Object.keys(config.agents ?? {}).map(async (agentName) => {
+        const context = await createAgentContext({ agentName, config });
+        return {
+          context,
+          jobs: createJobsForAgentContext(context),
+        };
+      }),
+    ).then((f) => f.flat()),
   };
 };

package/src/pipeline/createJobsForComponent.ts

@@ -39,5 +39,6 @@ export const createJobsForComponentContext = (
       : [];
 
   const customJobs = getCustomJobs(context);
+
   return [...buildJobs, ...deployJobs, ...customJobs];
 };

package/src/pipeline/createMainPipeline.ts

@@ -2,6 +2,7 @@ import {
   RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT,
   RULE_IS_MERGE_REQUEST,
   RULE_IS_TAGGED_RELEASE,
+  RULE_NEVER_ON_AGENT_TRIGGER,
 } from "../rules";
 import type {
   ComponentContext,
@@ -66,7 +67,16 @@ export const createMainPipeline = async <T extends PipelineType>(
         );
         return aIndex - bIndex;
       });
-    const allJobs = [...allWorkspaceJobs, ...allComponentJobs].reduce(
+
+    const allGlobalJobs = allJobsPerTrigger.filter(
+      (j) => j.context?.type === "agent",
+    );
+
+    const allJobs = [
+      ...allWorkspaceJobs,
+      ...allComponentJobs,
+      ...allGlobalJobs,
+    ].reduce(
       (acc, { gitlabJob, name, context }) => {
         // merge jobs, if a job is already there, merge the rules
         // this is currently needed because of envMode: "none", which creates the same job for all triggers, so it can appear multiple times
@@ -109,10 +119,15 @@ function getGitlabRulesForTrigger(trigger: PipelineTrigger): GitlabRule[] {
   // taggedRelease: on tag
   switch (trigger) {
     case "mainBranch":
-      return [RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT];
+      return [
+        RULE_NEVER_ON_AGENT_TRIGGER,
+        RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT,
+      ];
     case "mr":
-      return [RULE_IS_MERGE_REQUEST];
+      return [RULE_NEVER_ON_AGENT_TRIGGER, RULE_IS_MERGE_REQUEST];
     case "taggedRelease":
-      return [RULE_IS_TAGGED_RELEASE];
+      return [RULE_NEVER_ON_AGENT_TRIGGER, RULE_IS_TAGGED_RELEASE];
   }
+
+  throw new Error(`${trigger} is not supported`);
 }

package/src/pipeline/gitlab/createGitlabJobs.ts

@@ -2,6 +2,7 @@ import { isEmpty, isObject, merge } from "lodash";
 import { getInjectVarsScript } from "../../bash/getInjectVarsScript";
 import { BASE_RETRY } from "../../defaults";
 import type {
+  AgentContext,
   ComponentContext,
   Context,
   GitlabJobDef,
@@ -17,7 +18,7 @@ import { getBashVariable } from "../../bash/BashExpression";
 
 export type GitlabJobWithContext = {
   gitlabJob: GitlabJobDef;
-  context: Context | null;
+  context: Context | AgentContext | null;
 };
 export type AllGitlabJobs = (GitlabJobWithContext & { name: string })[];
 
@@ -29,14 +30,14 @@ const getFullJobName = ({
   allJobs,
   env,
 }: {
-  type: "component" | "workspace";
+  type: "component" | "workspace" | "agent";
   name: string;
   baseName: string;
   allJobs: AllCatladderJobs;
   env?: string | null;
 }) => {
   const shouldAddIcon = allJobs.workspaces.length > 0;
-  const icon = type === "component" ? "🔹" : "🔸";
+  const icon = type === "component" ? "🔹" : type === "agent" ? "🤖" : "🔸";
   const prefix = shouldAddIcon ? icon + " " : "";
   if (env) {
     return `${prefix}${baseName} ${name} | ${env} `;
@@ -98,7 +99,7 @@ const getJobName = (need: CatladderJobNeed) =>
   isObject(need) ? need.job : need;
 
 export const makeGitlabJob = (
-  context: Context,
+  context: Context | AgentContext,
   job: CatladderJob<string>,
   allJobs: AllCatladderJobs,
   baseRules?: GitlabRule[],
@@ -118,7 +119,9 @@ export const makeGitlabJob = (
     ...rest
   } = job;
   const stage =
-    envMode === "stagePerEnv" ? `${job.stage} ${context.env}` : job.stage;
+    envMode === "stagePerEnv" && context.type !== "agent"
+      ? `${job.stage} ${context.env}`
+      : job.stage;
 
   const deduplicatedGitlabNeeds: GitlabJobDef["needs"] = getGitlabNeeds(
     context,
@@ -130,7 +133,8 @@ export const makeGitlabJob = (
     type: context.type,
     name,
     baseName: context.name,
-    env: envMode !== "none" ? context.env : undefined,
+    env:
+      envMode !== "none" && context.type !== "agent" ? context.env : undefined,
     allJobs,
   });
 
@@ -184,6 +188,8 @@ export const makeGitlabJob = (
   ];
 
   const gitlabJob: GitlabJobDef = {
+    retry: BASE_RETRY,
+    interruptible: true,
     ...rest,
     rules: rules.length > 0 ? rules : undefined,
     variables: {
@@ -196,8 +202,6 @@ export const makeGitlabJob = (
 
     // sort in a predictable manner for snapshot tests
     needs: deduplicatedGitlabNeeds,
-    retry: BASE_RETRY,
-    interruptible: true,
   };
   const modified = addGitlabEnvironment(
     context,
@@ -210,7 +214,7 @@ export const makeGitlabJob = (
 };
 
 const addGitlabEnvironment = (
-  context: Context,
+  context: Context | AgentContext,
   catladderJobEnvironment: CatladderJob["environment"],
   job: GitlabJobDef,
   allJobs: AllCatladderJobs,
@@ -219,7 +223,7 @@ const addGitlabEnvironment = (
     return job;
   }
   if (context.type !== "component") {
-    // don't add enviornment for workspace jobs atm.
+    // don't add enviornment for workspace and agent jobs atm.
     return job;
   }
   const { env, name, environment } = context;
@@ -280,36 +284,41 @@ export const createGitlabJobs = async (
   baseRules?: GitlabRule[],
 ): Promise<AllGitlabJobs> => {
   // TODO: add workspace jobs
-  return [...allJobs.workspaces, ...allJobs.components].flatMap(
-    ({ context, jobs }) => {
-      return jobs.map((job) => {
-        const [fullJobName, gitlabJob] = makeGitlabJob(
-          context,
-          job,
-          allJobs,
-          baseRules,
-        );
-        return {
-          name: fullJobName,
-          gitlabJob,
-          context,
-        };
-      });
-    },
-  );
+
+  return [
+    ...allJobs.workspaces,
+    ...allJobs.components,
+    ...allJobs.agents,
+  ].flatMap(({ context, jobs }) => {
+    return jobs.map((job) => {
+      const [fullJobName, gitlabJob] = makeGitlabJob(
+        context,
+        job,
+        allJobs,
+        baseRules,
+      );
+      return {
+        name: fullJobName,
+        gitlabJob,
+        context,
+      };
+    });
+  });
 };
 
 function getGitlabNeeds(
-  context: Context,
+  context: Context | AgentContext,
   job: CatladderJob<string>,
   allJobs: AllCatladderJobs,
 ): GitlabJobDef["needs"] {
   const needs =
     context.type === "workspace"
       ? getGitlabNeedsForWorkspaceJob(context, job, allJobs)
-      : getGitlabNeedsForComponentJob(context, job, allJobs);
+      : context.type === "agent"
+        ? (job.needs ?? null)
+        : getGitlabNeedsForComponentJob(context, job, allJobs);
 
-  return deduplicateNeeds(needs);
+  return needs ? deduplicateNeeds(needs) : undefined;
 }
 function deduplicateNeeds(needs: GitlabJobDef["needs"]): GitlabJobDef["needs"] {
   return needs

package/src/pipeline/gitlab/createGitlabPipeline.ts

@@ -37,6 +37,13 @@ export const createGitlabPipelineWithDefaults = ({
     workflow: {
       name: "$PIPELINE_ICON $PIPELINE_NAME",
       rules: [
+        {
+          if: '$CI_PIPELINE_SOURCE  == "trigger"',
+          variables: {
+            PIPELINE_ICON: "🤖",
+            PIPELINE_NAME: "Thinking...",
+          },
+        },
         {
           if: RULE_IS_MERGE_REQUEST.if,
           variables: {
@@ -55,9 +62,10 @@ export const createGitlabPipelineWithDefaults = ({
           if: RULE_IS_MAIN_BRANCH_AND_NOT_RELEASE_COMMIT.if,
           variables: {
             PIPELINE_ICON: "🐱🔨",
-            PIPELINE_NAME: "Main $CI_COMMIT_REF_NAME",
+            PIPELINE_NAME: "Main",
           },
         },
+
         {
           when: "always", // fallback
           variables: {

package/src/rules/index.ts

@@ -18,6 +18,11 @@ export const RULE_NEVER_ON_RELEASE_COMMIT: GitlabRule = {
   if: RULE_CONDITION_RELEASE_COMMIT,
   when: "never",
 };
+// currently, we consider all triggered pipelines as agent triggers
+export const RULE_NEVER_ON_AGENT_TRIGGER: GitlabRule = {
+  if: '$CI_PIPELINE_SOURCE  == "trigger"',
+  when: "never",
+};
 
 export const RULE_NEVER_ON_SCHEDULE: GitlabRule = {
   if: '$CI_PIPELINE_SOURCE  == "schedule"',
@@ -37,6 +42,7 @@ export const RULE_CONDITION_HOTFIX_BRANCH =
 
 export const RULES_RELEASE: GitlabRule[] = [
   RULE_NEVER_ON_RELEASE_COMMIT,
+  RULE_NEVER_ON_AGENT_TRIGGER,
   RULE_NEVER_ON_SCHEDULE,
   {
     if: RULE_CONDITION_MAIN_BRANCH + ' && $AUTO_RELEASE == "true"',
@@ -54,6 +60,7 @@ export const RULES_RELEASE: GitlabRule[] = [
 
 export const RULES_MANUAL_RELEASE: GitlabRule[] = [
   RULE_NEVER_ON_RELEASE_COMMIT,
+  RULE_NEVER_ON_AGENT_TRIGGER,
   RULE_NEVER_ON_SCHEDULE,
   {
     if: RULE_CONDITION_MAIN_BRANCH,

package/src/types/agent.ts

@@ -0,0 +1,7 @@
+export type AgentConfig = {
+  type: "claude";
+  agentUser?: {
+    username: string;
+    userId: string;
+  };
+};

package/src/types/config.ts

@@ -5,6 +5,7 @@ import type { CatladderJob } from "./jobs";
 import type { ComponentContext } from "./context";
 import type { PartialDeep } from "./utils";
 import type { PipelineType, WorkspaceBuildConfig } from "..";
+import type { AgentConfig } from "./agent";
 
 export const ALL_PIPELINE_TRIGGERS = [
   "mainBranch",
@@ -210,6 +211,8 @@ export type Config<C extends ConfigProps = never> = {
    */
   domainCanonical?: string;
 
+  agents?: Record<string, AgentConfig>;
+
   // shared workspace Builds
   builds?: Record<string, WorkspaceBuildConfig>;
   /**

package/src/types/context.ts

@@ -7,6 +7,7 @@ import type {
 import type { PredefinedVariables, SecretEnvVar } from "../context";
 import type { DeployConfig } from "../deploy";
 import type { VariableValue } from "../variables/VariableValue";
+import type { AgentConfig } from "./agent";
 import type {
   ComponentConfig,
   Config,
@@ -214,3 +215,10 @@ export type WorkspaceContext = {
   pipelineType: PipelineType;
   env: string;
 };
+
+export type AgentContext = {
+  type: "agent";
+  name: string;
+  fullConfig: Config;
+  agentConfig: AgentConfig;
+};

package/src/types/index.ts

@@ -4,3 +4,4 @@ export * from "./context";
 export * from "./jobDefinition";
 export * from "./pipeline";
 export * from "./jobs";
+export * from "./agent";

package/src/types/jobs.ts

@@ -15,6 +15,7 @@ export const BASE_STAGES = [
   "build",
   "deploy",
   "verify",
+  "agents",
   "rollback",
   "stop",
 ] as const;
@@ -129,4 +130,9 @@ export type CatladderJob<S = BaseStage> = {
    * tags for the underlying job runner (e.g gitlab)
    */
   jobTags?: string[];
+
+  /**
+   * whether the job is interruptible (default: true)
+   */
+  interruptible?: boolean;
 };