@octo-cyber/ai 0.5.4 → 0.5.6

package/dist/shared/IClaudeCodeSessionManager.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Session status for a Claude Code agent session.
+ *
+ * - `starting`  — worktree created, process being launched
+ * - `running`   — Claude Code agent is actively executing
+ * - `completed` — agent finished successfully (PR submitted or task done)
+ * - `failed`    — agent exited with error or timed out
+ * - `cancelled` — session was manually stopped before completion
+ */
+export type ClaudeCodeSessionStatus = 'starting' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Options passed when starting a new Claude Code session.
+ */
+export interface StartSessionOptions {
+    /** Identifier of the feedback requirement that triggered this session. */
+    requirementId: string;
+    /** Absolute path to the git worktree where Claude Code will run. */
+    worktreePath: string;
+    /** Branch name checked out in the worktree (e.g. `claude/task-042-fix-login`). */
+    branch: string;
+    /**
+     * Optional path to the TASK.md file inside the worktree.
+     * When provided, Claude Code reads this file as its primary directive.
+     */
+    taskFilePath?: string;
+    /**
+     * Maximum time (in milliseconds) to allow the session to run before
+     * it is treated as timed-out and killed. Defaults to 86_400_000 (24 h).
+     */
+    timeoutMs?: number;
+}
+/**
+ * Snapshot of a running or finished Claude Code session.
+ */
+export interface ClaudeCodeSession {
+    /** Unique session identifier (UUID). */
+    sessionId: string;
+    /** Requirement that triggered this session. */
+    requirementId: string;
+    /** Current lifecycle status of the session. */
+    status: ClaudeCodeSessionStatus;
+    /** Absolute path to the worktree where the agent is (or was) running. */
+    worktreePath: string;
+    /** Branch checked out in the worktree. */
+    branch: string;
+    /** Wall-clock time when the session was created. */
+    startedAt: Date;
+    /**
+     * Wall-clock time when the session reached a terminal state
+     * (`completed`, `failed`, or `cancelled`). Undefined while still active.
+     */
+    endedAt?: Date;
+    /**
+     * URL of the pull request created by this session.
+     * Populated only after the agent calls `/ship` and the PR is opened.
+     */
+    prUrl?: string;
+    /**
+     * Human-readable error message when `status` is `failed`.
+     * Undefined for successful or in-progress sessions.
+     */
+    error?: string;
+}
+/**
+ * Result returned by {@link IClaudeCodeSessionManager.stopSession}.
+ */
+export interface StopSessionResult {
+    /** Whether the session was successfully stopped. */
+    success: boolean;
+    /** Final status after the stop attempt. */
+    finalStatus: ClaudeCodeSessionStatus;
+    /** Error message if the stop operation itself failed. */
+    error?: string;
+}
+/**
+ * Contract for managing Claude Code agent sessions within the Octo
+ * self-iteration pipeline.
+ *
+ * Implementations are responsible for:
+ * 1. Spawning Claude Code processes inside git worktrees.
+ * 2. Tracking session lifecycle (starting → running → completed/failed).
+ * 3. Enforcing per-session timeouts and concurrency limits.
+ * 4. Persisting session state so callers can resume across service restarts.
+ *
+ * @example
+ * ```typescript
+ * const manager = Container.get(IClaudeCodeSessionManager);
+ *
+ * const session = await manager.startSession({
+ *   requirementId: 'req-abc123',
+ *   worktreePath: '/path/to/worktree',
+ *   branch: 'claude/task-007-fix-auth',
+ *   taskFilePath: '/path/to/worktree/doc/task/TASK-007-fix-auth.md',
+ * });
+ *
+ * console.log(session.sessionId); // 'f47ac10b-...'
+ * ```
+ */
+export interface IClaudeCodeSessionManager {
+    /**
+     * Launches a new Claude Code agent session inside the given worktree.
+     *
+     * The implementation MUST:
+     * - Be idempotent for the same `requirementId`: if a session is already
+     *   `starting` or `running` for that requirement, return the existing session
+     *   rather than spawning a second process.
+     * - Persist the session record before returning so that a crash of the host
+     *   process does not silently lose in-flight work.
+     * - Enforce `timeoutMs`: kill the process and set status to `failed` if it
+     *   runs longer than allowed.
+     *
+     * @param options - Configuration for the new session.
+     * @returns The created (or existing) session record.
+     * @throws {Error} If the worktree path does not exist or is not a git repo.
+     */
+    startSession(options: StartSessionOptions): Promise<ClaudeCodeSession>;
+    /**
+     * Requests graceful termination of an active session.
+     *
+     * The implementation SHOULD:
+     * - Send SIGTERM first, then SIGKILL after a short grace period (default 5 s).
+     * - Set status to `cancelled` on success.
+     * - Be a no-op (return success) if the session is already in a terminal state.
+     *
+     * @param sessionId - The UUID of the session to stop.
+     * @returns Result indicating whether the session was successfully stopped.
+     */
+    stopSession(sessionId: string): Promise<StopSessionResult>;
+    /**
+     * Returns the current snapshot of a session.
+     *
+     * @param sessionId - The UUID of the session to look up.
+     * @returns The session record, or `undefined` if no such session exists.
+     */
+    getSessionStatus(sessionId: string): Promise<ClaudeCodeSession | undefined>;
+    /**
+     * Lists all sessions that are currently in an active state
+     * (`starting` or `running`).
+     *
+     * Useful for:
+     * - Dashboard display of in-progress AI development tasks.
+     * - Recovery logic on service startup (detect orphaned sessions).
+     * - Enforcing global concurrency limits.
+     *
+     * @returns Array of active session records, ordered by `startedAt` ascending.
+     */
+    listActiveSessions(): Promise<ClaudeCodeSession[]>;
+}
+/** DI token for resolving {@link IClaudeCodeSessionManager} implementations. */
+export declare const CLAUDE_CODE_SESSION_MANAGER: unique symbol;
+//# sourceMappingURL=IClaudeCodeSessionManager.d.ts.map

package/dist/shared/IClaudeCodeSessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IClaudeCodeSessionManager.d.ts","sourceRoot":"","sources":["../../shared/IClaudeCodeSessionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B,UAAU,GACV,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,MAAM,EAAE,uBAAuB,CAAC;IAChC,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,IAAI,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,WAAW,EAAE,uBAAuB,CAAC;IACrC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEvE;;;;;;;;;;OAUG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE3D;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IAE5E;;;;;;;;;;OAUG;IACH,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CACpD;AAED,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,eAAsC,CAAC"}

package/dist/shared/IClaudeCodeSessionManager.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_CODE_SESSION_MANAGER = void 0;
+/** DI token for resolving {@link IClaudeCodeSessionManager} implementations. */
+exports.CLAUDE_CODE_SESSION_MANAGER = Symbol('IClaudeCodeSessionManager');
+//# sourceMappingURL=IClaudeCodeSessionManager.js.map

package/dist/shared/IClaudeCodeSessionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IClaudeCodeSessionManager.js","sourceRoot":"","sources":["../../shared/IClaudeCodeSessionManager.ts"],"names":[],"mappings":";;;AAiKA,gFAAgF;AACnE,QAAA,2BAA2B,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC"}

package/dist/src/BranchDecisionEngine.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Requirement type accepted by the decision engine.
+ * Maps directly to `FeedbackItem.type` values used in the self-iteration
+ * pipeline.
+ */
+export type RequirementType = 'bug' | 'enhancement' | 'new_feature' | 'arch';
+/**
+ * Branch strategy produced by the decision engine.
+ *
+ * | Strategy     | Meaning                                                        |
+ * |--------------|----------------------------------------------------------------|
+ * | `hotfix`     | Minimal patch on the current stable branch (bug fixes, typos) |
+ * | `feature`    | Feature branch off the current integration branch             |
+ * | `experiment` | Isolated long-lived branch for architectural exploration       |
+ */
+export type BranchStrategy = 'hotfix' | 'feature' | 'experiment';
+/**
+ * Full decision record returned by {@link BranchDecisionEngine.decide}.
+ */
+export interface BranchDecision {
+    /** Chosen branch strategy. */
+    strategy: BranchStrategy;
+    /**
+     * Human-readable explanation of why this strategy was selected.
+     * Recorded in the generated TASK.md for traceability.
+     */
+    rationale: string;
+    /**
+     * Confidence score in the range [0, 1].
+     * Scores below 0.8 should trigger a human-confirmation step before
+     * automatically dispatching a worktree (per n8n workflow design).
+     */
+    confidence: number;
+}
+/**
+ * Input to the decision engine.
+ */
+export interface DecisionInput {
+    /** Requirement type from the feedback item. */
+    type: RequirementType;
+    /**
+     * Full text of the requirement (title + content).
+     * Used for keyword matching when the type alone is ambiguous.
+     */
+    text: string;
+}
+/**
+ * Rule-based branch strategy decision engine for the Octo self-iteration
+ * pipeline.
+ *
+ * Evaluates a prioritised rule table against the requirement type and
+ * free-text content to select the appropriate git branch strategy.
+ *
+ * This is a pure, stateless function object — no DI, no I/O.
+ * It can be unit-tested without any infrastructure setup.
+ *
+ * @example
+ * ```typescript
+ * const engine = new BranchDecisionEngine();
+ * const decision = engine.decide({ type: 'bug', text: '登录页崩溃 null error' });
+ * // → { strategy: 'hotfix', confidence: 0.95, rationale: '...' }
+ * ```
+ */
+export declare class BranchDecisionEngine {
+    /**
+     * Evaluates the rule table and returns the first matching branch decision.
+     *
+     * @param input - Requirement type and full text content.
+     * @returns The selected {@link BranchDecision}.
+     */
+    decide(input: DecisionInput): BranchDecision;
+}
+//# sourceMappingURL=BranchDecisionEngine.d.ts.map

package/dist/src/BranchDecisionEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchDecisionEngine.d.ts","sourceRoot":"","sources":["../../src/BranchDecisionEngine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,CAAC;AAE7E;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,EAAE,cAAc,CAAC;IACzB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,eAAe,CAAC;IACtB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AA8LD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAoB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc;CAoB7C"}

package/dist/src/BranchDecisionEngine.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchDecisionEngine = void 0;
+// ── Keyword lists ─────────────────────────────────────────────────────────────
+/**
+ * Keywords that strongly indicate a production defect requiring an urgent
+ * hotfix regardless of the nominal `type` field.
+ */
+const CRASH_KEYWORDS = [
+    '错误',
+    '崩溃',
+    '报错',
+    'exception',
+    'null',
+    'undefined',
+    'crash',
+    'fatal',
+    'panic',
+    '异常',
+    '挂了',
+    '无法启动',
+    '白屏',
+    '500',
+    'error',
+];
+/**
+ * Keywords that suggest the requirement involves introducing a brand-new
+ * `@octo-cyber/*` package or cross-module architecture work, pushing the
+ * decision toward the `experiment` strategy.
+ */
+const ARCH_KEYWORDS = [
+    'arch',
+    '架构',
+    'breaking',
+    'refactor',
+    '重构',
+    'new package',
+    '新包',
+    '@octo-cyber',
+    'major',
+    'v0.6',
+    'v1.0',
+    '跨模块',
+];
+/**
+ * Keywords that indicate a new, self-contained feature that can be developed
+ * on a regular feature branch.
+ */
+const NEW_MODULE_KEYWORDS = [
+    'new module',
+    '新模块',
+    'new page',
+    '新页面',
+    'new feature',
+    '新功能',
+    'integration',
+    '集成',
+];
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function containsAny(text, keywords) {
+    const lower = text.toLowerCase();
+    return keywords.some((kw) => lower.includes(kw.toLowerCase()));
+}
+// Pre-sorted by priority so decide() incurs no per-call sort overhead.
+const RULES = [
+    // ── P0: Crash / error keywords override everything ──────────────────────────
+    {
+        priority: 0,
+        description: 'Crash/error keywords detected — urgent hotfix',
+        matches: ({ text }) => containsAny(text, CRASH_KEYWORDS),
+        strategy: 'hotfix',
+        rationale: () => '检测到崩溃/错误关键词，判定为紧急缺陷，采用 hotfix 策略直接基于稳定分支修复',
+        confidence: 0.95,
+    },
+    // ── P1: Explicit bug type ────────────────────────────────────────────────────
+    {
+        priority: 1,
+        description: 'type=bug — hotfix',
+        matches: ({ type }) => type === 'bug',
+        strategy: 'hotfix',
+        rationale: () => 'type=bug，采用 hotfix 策略，基于当前稳定分支修复缺陷',
+        confidence: 0.9,
+    },
+    // ── P2: Arch / breaking change ───────────────────────────────────────────────
+    {
+        priority: 2,
+        description: 'type=arch OR arch keywords — experiment branch',
+        matches: ({ type, text }) => type === 'arch' || containsAny(text, ARCH_KEYWORDS),
+        strategy: 'experiment',
+        rationale: ({ type, text }) => {
+            if (type === 'arch') {
+                return 'type=arch，架构级变更采用独立 experiment 分支，需人工确认后合并';
+            }
+            return `检测到架构关键词（${ARCH_KEYWORDS.find((kw) => text.toLowerCase().includes(kw.toLowerCase()))}），涉及跨模块或大型重构，采用 experiment 分支隔离风险`;
+        },
+        confidence: 0.85,
+    },
+    // ── P3: new_feature with new @octo-cyber/* package signals ──────────────────
+    {
+        priority: 3,
+        description: 'new_feature + new-module keywords — experiment branch',
+        matches: ({ type, text }) => type === 'new_feature' && containsAny(text, ARCH_KEYWORDS),
+        strategy: 'experiment',
+        rationale: () => 'new_feature 需要新建 @octo-cyber/* 包或涉及跨模块架构，采用 experiment 分支独立演进',
+        confidence: 0.8,
+    },
+    // ── P4: new_feature within existing modules ──────────────────────────────────
+    {
+        priority: 4,
+        description: 'new_feature — feature branch',
+        matches: ({ type }) => type === 'new_feature',
+        strategy: 'feature',
+        rationale: ({ text }) => {
+            if (containsAny(text, NEW_MODULE_KEYWORDS)) {
+                return 'new_feature 涉及新页面或新功能模块，在现有模块内扩展，采用 feature 分支开发';
+            }
+            return 'new_feature 在现有模块可扩展范围内，采用 feature 分支，合并到 v0.5 主干';
+        },
+        confidence: 0.85,
+    },
+    // ── P5: Small enhancement (≤200 chars) ──────────────────────────────────────
+    {
+        priority: 5,
+        description: 'enhancement + short content — hotfix',
+        matches: ({ type, text }) => type === 'enhancement' && text.length <= 200,
+        strategy: 'hotfix',
+        rationale: () => 'enhancement 内容较短（≤200字），判定为小改动，采用 hotfix 策略快速交付',
+        confidence: 0.8,
+    },
+    // ── P6: Larger enhancement ───────────────────────────────────────────────────
+    {
+        priority: 6,
+        description: 'enhancement + longer content — feature branch',
+        matches: ({ type }) => type === 'enhancement',
+        strategy: 'feature',
+        rationale: () => 'enhancement 内容较长（>200字），可能涉及新字段或新流程，采用 feature 分支开发，功能开关控制上线',
+        confidence: 0.75,
+    },
+    // ── P7: Fallback ─────────────────────────────────────────────────────────────
+    {
+        priority: 7,
+        description: 'fallback — feature branch, low confidence',
+        matches: () => true,
+        strategy: 'feature',
+        rationale: () => '无法匹配明确规则，默认采用 feature 分支，置信度较低，建议人工确认分支策略',
+        confidence: 0.5,
+    },
+];
+// ── Engine ────────────────────────────────────────────────────────────────────
+/**
+ * Rule-based branch strategy decision engine for the Octo self-iteration
+ * pipeline.
+ *
+ * Evaluates a prioritised rule table against the requirement type and
+ * free-text content to select the appropriate git branch strategy.
+ *
+ * This is a pure, stateless function object — no DI, no I/O.
+ * It can be unit-tested without any infrastructure setup.
+ *
+ * @example
+ * ```typescript
+ * const engine = new BranchDecisionEngine();
+ * const decision = engine.decide({ type: 'bug', text: '登录页崩溃 null error' });
+ * // → { strategy: 'hotfix', confidence: 0.95, rationale: '...' }
+ * ```
+ */
+class BranchDecisionEngine {
+    /**
+     * Evaluates the rule table and returns the first matching branch decision.
+     *
+     * @param input - Requirement type and full text content.
+     * @returns The selected {@link BranchDecision}.
+     */
+    decide(input) {
+        for (const rule of RULES) {
+            if (rule.matches(input)) {
+                return {
+                    strategy: rule.strategy,
+                    rationale: rule.rationale(input),
+                    confidence: rule.confidence,
+                };
+            }
+        }
+        // The fallback rule (priority 7) always matches, so this is unreachable.
+        // Included for TypeScript exhaustiveness.
+        /* istanbul ignore next */
+        return {
+            strategy: 'feature',
+            rationale: '未匹配任何规则，使用默认 feature 策略',
+            confidence: 0.5,
+        };
+    }
+}
+exports.BranchDecisionEngine = BranchDecisionEngine;
+//# sourceMappingURL=BranchDecisionEngine.js.map

package/dist/src/BranchDecisionEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchDecisionEngine.js","sourceRoot":"","sources":["../../src/BranchDecisionEngine.ts"],"names":[],"mappings":"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"}

package/dist/src/agent/agent-approval.controller.d.ts

@@ -0,0 +1,20 @@
+import type { Request, Response } from '@octo-cyber/core';
+/**
+ * AgentApprovalController — human-in-the-loop approval API.
+ *
+ * Endpoints:
+ *   POST /api/v1/ai/agent/approval             — Create an approval request
+ *   GET  /api/v1/ai/agent/approval/pending     — List pending approvals
+ *   GET  /api/v1/ai/agent/approval/:id         — Get a specific approval
+ *   POST /api/v1/ai/agent/approval/:id/approve — Approve a request
+ *   POST /api/v1/ai/agent/approval/:id/reject  — Reject a request
+ */
+export declare class AgentApprovalController {
+    private get service();
+    createApproval(req: Request, res: Response): Promise<void>;
+    listPending(_req: Request, res: Response): Promise<void>;
+    getApproval(req: Request, res: Response): Promise<void>;
+    approveRequest(req: Request, res: Response): Promise<void>;
+    rejectRequest(req: Request, res: Response): Promise<void>;
+}
+//# sourceMappingURL=agent-approval.controller.d.ts.map

package/dist/src/agent/agent-approval.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-approval.controller.d.ts","sourceRoot":"","sources":["../../../src/agent/agent-approval.controller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG1D;;;;;;;;;GASG;AACH,qBACa,uBAAuB;IAClC,OAAO,KAAK,OAAO,GAElB;IAGK,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB1D,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvD,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAOhE"}

package/dist/src/agent/agent-approval.controller.js

@@ -0,0 +1,101 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentApprovalController = void 0;
+const core_1 = require("@octo-cyber/core");
+const agent_approval_service_js_1 = require("./agent-approval.service.js");
+/**
+ * AgentApprovalController — human-in-the-loop approval API.
+ *
+ * Endpoints:
+ *   POST /api/v1/ai/agent/approval             — Create an approval request
+ *   GET  /api/v1/ai/agent/approval/pending     — List pending approvals
+ *   GET  /api/v1/ai/agent/approval/:id         — Get a specific approval
+ *   POST /api/v1/ai/agent/approval/:id/approve — Approve a request
+ *   POST /api/v1/ai/agent/approval/:id/reject  — Reject a request
+ */
+let AgentApprovalController = class AgentApprovalController {
+    get service() {
+        return core_1.Container.get(agent_approval_service_js_1.AgentApprovalService);
+    }
+    async createApproval(req, res) {
+        const body = req.body;
+        if (!body.runId || typeof body.runId !== 'string' || body.runId.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid runId');
+        }
+        if (!body.question || typeof body.question !== 'string' || body.question.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid question');
+        }
+        const context = typeof body.context === 'string' ? body.context : undefined;
+        const approval = await this.service.create(body.runId.trim(), body.question.trim(), context);
+        res.json(core_1.ApiResponse.ok(this.service.toDto(approval)));
+    }
+    async listPending(_req, res) {
+        const approvals = await this.service.getPending();
+        res.json(core_1.ApiResponse.ok(approvals.map((a) => this.service.toDto(a))));
+    }
+    async getApproval(req, res) {
+        const id = String(req.params['id'] ?? '');
+        const approval = await this.service.getById(id);
+        if (!approval)
+            throw core_1.AppError.notFound(`Agent approval not found: ${id}`);
+        res.json(core_1.ApiResponse.ok(this.service.toDto(approval)));
+    }
+    async approveRequest(req, res) {
+        const id = String(req.params['id'] ?? '');
+        const body = req.body;
+        const response = typeof body.response === 'string' ? body.response : undefined;
+        const approval = await this.service.respond(id, true, response);
+        res.json(core_1.ApiResponse.ok(this.service.toDto(approval)));
+    }
+    async rejectRequest(req, res) {
+        const id = String(req.params['id'] ?? '');
+        const body = req.body;
+        const response = typeof body.response === 'string' ? body.response : undefined;
+        const approval = await this.service.respond(id, false, response);
+        res.json(core_1.ApiResponse.ok(this.service.toDto(approval)));
+    }
+};
+exports.AgentApprovalController = AgentApprovalController;
+__decorate([
+    (0, core_1.Post)('/approval'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AgentApprovalController.prototype, "createApproval", null);
+__decorate([
+    (0, core_1.Get)('/approval/pending'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AgentApprovalController.prototype, "listPending", null);
+__decorate([
+    (0, core_1.Get)('/approval/:id'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AgentApprovalController.prototype, "getApproval", null);
+__decorate([
+    (0, core_1.Post)('/approval/:id/approve'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AgentApprovalController.prototype, "approveRequest", null);
+__decorate([
+    (0, core_1.Post)('/approval/:id/reject'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AgentApprovalController.prototype, "rejectRequest", null);
+exports.AgentApprovalController = AgentApprovalController = __decorate([
+    (0, core_1.Controller)('/api/v1/ai/agent')
+], AgentApprovalController);
+//# sourceMappingURL=agent-approval.controller.js.map

package/dist/src/agent/agent-approval.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-approval.controller.js","sourceRoot":"","sources":["../../../src/agent/agent-approval.controller.ts"],"names":[],"mappings":"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"}

package/dist/src/agent/agent-approval.entity.d.ts

@@ -0,0 +1,15 @@
+export type AgentApprovalStatus = 'pending' | 'approved' | 'rejected';
+export declare class AgentApproval {
+    id: string;
+    runId: string;
+    /** The question or action description requiring human approval. */
+    question: string;
+    /** Optional JSON or text context to help the reviewer decide. */
+    context: string | null;
+    status: AgentApprovalStatus;
+    /** Optional response message from the human reviewer. */
+    response: string | null;
+    respondedAt: Date | null;
+    createdAt: Date;
+}
+//# sourceMappingURL=agent-approval.entity.d.ts.map

package/dist/src/agent/agent-approval.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-approval.entity.d.ts","sourceRoot":"","sources":["../../../src/agent/agent-approval.entity.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAEtE,qBACa,aAAa;IAExB,EAAE,EAAG,MAAM,CAAC;IAGZ,KAAK,EAAG,MAAM,CAAC;IAEf,mEAAmE;IAEnE,QAAQ,EAAG,MAAM,CAAC;IAElB,iEAAiE;IAEjE,OAAO,EAAG,MAAM,GAAG,IAAI,CAAC;IAGxB,MAAM,EAAG,mBAAmB,CAAC;IAE7B,yDAAyD;IAEzD,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAGzB,WAAW,EAAG,IAAI,GAAG,IAAI,CAAC;IAG1B,SAAS,EAAG,IAAI,CAAC;CAClB"}