@a5c-ai/tasks-adapter 5.1.1-staging.0ad6ac75ae4a

package/dist/auth/jwt.js

@@ -0,0 +1,43 @@
+import jwt from "jsonwebtoken";
+import { JWTPayloadSchema } from "./types.js";
+// ── Constants ─────────────────────────────────────────────────────────────
+const ALGORITHM = "HS256";
+const DEFAULT_ACCESS_TOKEN_EXPIRY = "1h";
+const DEFAULT_REFRESH_TOKEN_EXPIRY = "7d";
+// ── Sign / Verify ─────────────────────────────────────────────────────────
+/**
+ * Sign a JWT access token with the given payload and secret.
+ */
+export function signAccessToken(payload, secret, expiresIn = DEFAULT_ACCESS_TOKEN_EXPIRY) {
+    return jwt.sign({ ...payload, type: "access" }, secret, { algorithm: ALGORITHM, expiresIn });
+}
+/**
+ * Sign a JWT refresh token with the given payload and secret.
+ */
+export function signRefreshToken(payload, secret, expiresIn = DEFAULT_REFRESH_TOKEN_EXPIRY) {
+    return jwt.sign({ ...payload, type: "refresh" }, secret, { algorithm: ALGORITHM, expiresIn });
+}
+/**
+ * Verify a JWT token and return its decoded payload.
+ * Throws if the token is invalid or expired.
+ */
+export function verifyToken(token, secret) {
+    const decoded = jwt.verify(token, secret, { algorithms: [ALGORITHM] });
+    const result = JWTPayloadSchema.parse(decoded);
+    return result;
+}
+/**
+ * Refresh an access token using a valid refresh token.
+ * Returns a new access token and a new refresh token.
+ */
+export function refreshAccessToken(refreshToken, secret) {
+    const payload = verifyToken(refreshToken, secret);
+    if (payload.type !== "refresh") {
+        throw new Error("Token is not a refresh token");
+    }
+    const tokenPayload = { sub: payload.sub, login: payload.login, name: payload.name };
+    return {
+        accessToken: signAccessToken(tokenPayload, secret),
+        refreshToken: signRefreshToken(tokenPayload, secret),
+    };
+}

package/dist/auth/middleware.d.ts

@@ -0,0 +1,22 @@
+import type { Request, Response, NextFunction } from "express";
+import type { JWTPayload } from "./types.js";
+declare module "express" {
+    interface Request {
+        user?: JWTPayload;
+    }
+}
+export interface AuthMiddlewareOpts {
+    /** The secret used to verify JWT tokens. */
+    secret: string;
+    /** If true, returns 401 on missing or invalid token. Defaults to false. */
+    required?: boolean;
+}
+/**
+ * Create Express middleware that extracts and verifies a JWT from the
+ * Authorization: Bearer header.
+ *
+ * If `required` is true, returns 401 on missing or invalid tokens.
+ * If `required` is false (default), continues without auth when no token is present.
+ */
+export declare function createAuthMiddleware(opts: AuthMiddlewareOpts): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/auth/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,OAAO;QACf,IAAI,CAAC,EAAE,UAAU,CAAC;KACnB;CACF;AAID,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,kBAAkB,GACvB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CA6B3D"}

package/dist/auth/middleware.js

@@ -0,0 +1,36 @@
+import { verifyToken } from "./jwt.js";
+// ── Middleware ─────────────────────────────────────────────────────────────
+/**
+ * Create Express middleware that extracts and verifies a JWT from the
+ * Authorization: Bearer header.
+ *
+ * If `required` is true, returns 401 on missing or invalid tokens.
+ * If `required` is false (default), continues without auth when no token is present.
+ */
+export function createAuthMiddleware(opts) {
+    const { secret, required = false } = opts;
+    return (req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader || !authHeader.startsWith("Bearer ")) {
+            if (required) {
+                res.status(401).json({ error: "Authorization header with Bearer token is required" });
+                return;
+            }
+            next();
+            return;
+        }
+        const token = authHeader.slice(7);
+        try {
+            const payload = verifyToken(token, secret);
+            req.user = payload;
+            next();
+        }
+        catch {
+            if (required) {
+                res.status(401).json({ error: "Invalid or expired token" });
+                return;
+            }
+            next();
+        }
+    };
+}

package/dist/auth/ssh-keys.d.ts

@@ -0,0 +1,21 @@
+import type { SSHKeyPair } from "./types.js";
+/**
+ * Generate an Ed25519 SSH key pair.
+ */
+export declare function generateSSHKeyPair(): SSHKeyPair;
+/**
+ * Parse a public key string and return its algorithm and fingerprint.
+ */
+export declare function parsePublicKey(key: string): {
+    algorithm: string;
+    fingerprint: string;
+};
+/**
+ * Calculate the SHA256 fingerprint of a public key (base64 encoded).
+ */
+export declare function calculateFingerprint(publicKey: string): string;
+/**
+ * Format a public key as an authorized_keys entry with an optional comment.
+ */
+export declare function formatAuthorizedKey(publicKey: string, comment?: string): string;
+//# sourceMappingURL=ssh-keys.d.ts.map

package/dist/auth/ssh-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh-keys.d.ts","sourceRoot":"","sources":["../../src/auth/ssh-keys.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ7C;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,CAe/C;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CActF;AAID;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG9D;AAID;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAM/E"}

package/dist/auth/ssh-keys.js

@@ -0,0 +1,59 @@
+import { generateKeyPairSync, createHash } from "node:crypto";
+// ── Constants ─────────────────────────────────────────────────────────────
+const DEFAULT_ALGORITHM = "ed25519";
+// ── Key Generation ────────────────────────────────────────────────────────
+/**
+ * Generate an Ed25519 SSH key pair.
+ */
+export function generateSSHKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const fingerprint = calculateFingerprint(publicKey);
+    return {
+        publicKey,
+        privateKey,
+        fingerprint,
+        algorithm: DEFAULT_ALGORITHM,
+        createdAt: new Date().toISOString(),
+    };
+}
+// ── Key Parsing ───────────────────────────────────────────────────────────
+/**
+ * Parse a public key string and return its algorithm and fingerprint.
+ */
+export function parsePublicKey(key) {
+    const fingerprint = calculateFingerprint(key);
+    // Detect algorithm from key content
+    let algorithm = "unknown";
+    if (key.includes("ssh-ed25519") || key.includes("ED25519")) {
+        algorithm = "ed25519";
+    }
+    else if (key.includes("ssh-rsa") || key.includes("RSA")) {
+        algorithm = "rsa";
+    }
+    else if (key.includes("ecdsa") || key.includes("EC")) {
+        algorithm = "ecdsa";
+    }
+    return { algorithm, fingerprint };
+}
+// ── Fingerprint ───────────────────────────────────────────────────────────
+/**
+ * Calculate the SHA256 fingerprint of a public key (base64 encoded).
+ */
+export function calculateFingerprint(publicKey) {
+    const hash = createHash("sha256").update(publicKey.trim()).digest("base64");
+    return `SHA256:${hash}`;
+}
+// ── Formatting ────────────────────────────────────────────────────────────
+/**
+ * Format a public key as an authorized_keys entry with an optional comment.
+ */
+export function formatAuthorizedKey(publicKey, comment) {
+    const trimmed = publicKey.trim();
+    if (comment) {
+        return `${trimmed} ${comment}`;
+    }
+    return trimmed;
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+export declare const UserSchema: z.ZodObject<{
+    id: z.ZodString;
+    login: z.ZodString;
+    name: z.ZodString;
+    email: z.ZodString;
+    avatarUrl: z.ZodString;
+    provider: z.ZodLiteral<"github">;
+}, "strip", z.ZodTypeAny, {
+    provider: "github";
+    id: string;
+    name: string;
+    login: string;
+    email: string;
+    avatarUrl: string;
+}, {
+    provider: "github";
+    id: string;
+    name: string;
+    login: string;
+    email: string;
+    avatarUrl: string;
+}>;
+export type User = z.infer<typeof UserSchema>;
+export declare const AuthTokenSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+    expiresAt: z.ZodString;
+    user: z.ZodObject<{
+        id: z.ZodString;
+        login: z.ZodString;
+        name: z.ZodString;
+        email: z.ZodString;
+        avatarUrl: z.ZodString;
+        provider: z.ZodLiteral<"github">;
+    }, "strip", z.ZodTypeAny, {
+        provider: "github";
+        id: string;
+        name: string;
+        login: string;
+        email: string;
+        avatarUrl: string;
+    }, {
+        provider: "github";
+        id: string;
+        name: string;
+        login: string;
+        email: string;
+        avatarUrl: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    user: {
+        provider: "github";
+        id: string;
+        name: string;
+        login: string;
+        email: string;
+        avatarUrl: string;
+    };
+    accessToken: string;
+    refreshToken: string;
+}, {
+    expiresAt: string;
+    user: {
+        provider: "github";
+        id: string;
+        name: string;
+        login: string;
+        email: string;
+        avatarUrl: string;
+    };
+    accessToken: string;
+    refreshToken: string;
+}>;
+export type AuthToken = z.infer<typeof AuthTokenSchema>;
+export declare const JWTPayloadSchema: z.ZodObject<{
+    sub: z.ZodString;
+    login: z.ZodString;
+    name: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+    type: z.ZodEnum<["access", "refresh"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "access" | "refresh";
+    name: string;
+    sub: string;
+    login: string;
+    iat: number;
+    exp: number;
+}, {
+    type: "access" | "refresh";
+    name: string;
+    sub: string;
+    login: string;
+    iat: number;
+    exp: number;
+}>;
+export type JWTPayload = z.infer<typeof JWTPayloadSchema>;
+export declare const SSHKeyPairSchema: z.ZodObject<{
+    publicKey: z.ZodString;
+    privateKey: z.ZodString;
+    fingerprint: z.ZodString;
+    algorithm: z.ZodString;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    publicKey: string;
+    privateKey: string;
+    fingerprint: string;
+    algorithm: string;
+}, {
+    createdAt: string;
+    publicKey: string;
+    privateKey: string;
+    fingerprint: string;
+    algorithm: string;
+}>;
+export type SSHKeyPair = z.infer<typeof SSHKeyPairSchema>;
+export declare const GitForgeConfigSchema: z.ZodObject<{
+    type: z.ZodEnum<["github", "gitlab", "bitbucket"]>;
+    baseUrl: z.ZodString;
+    credentials: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github" | "gitlab" | "bitbucket";
+    baseUrl: string;
+    credentials: Record<string, string>;
+}, {
+    type: "github" | "gitlab" | "bitbucket";
+    baseUrl: string;
+    credentials: Record<string, string>;
+}>;
+export type GitForgeConfig = z.infer<typeof GitForgeConfigSchema>;
+export declare const GitHubOAuthConfigSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    callbackUrl: z.ZodString;
+    scopes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    scopes: string[];
+}, {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    scopes: string[];
+}>;
+export type GitHubOAuthConfig = z.infer<typeof GitHubOAuthConfigSchema>;
+export declare const GitHubAppConfigSchema: z.ZodObject<{
+    appId: z.ZodString;
+    privateKey: z.ZodString;
+    webhookSecret: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    privateKey: string;
+    appId: string;
+    webhookSecret?: string | undefined;
+}, {
+    privateKey: string;
+    appId: string;
+    webhookSecret?: string | undefined;
+}>;
+export type GitHubAppConfig = z.infer<typeof GitHubAppConfigSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;EAOrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAI9C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAO3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;EAM3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAI/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;EAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/auth/types.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+// ── User ──────────────────────────────────────────────────────────────────
+export const UserSchema = z.object({
+    id: z.string().min(1),
+    login: z.string().min(1),
+    name: z.string().min(1),
+    email: z.string().email(),
+    avatarUrl: z.string().url(),
+    provider: z.literal("github"),
+});
+// ── AuthToken ─────────────────────────────────────────────────────────────
+export const AuthTokenSchema = z.object({
+    accessToken: z.string().min(1),
+    refreshToken: z.string().min(1),
+    expiresAt: z.string().datetime(),
+    user: UserSchema,
+});
+// ── JWTPayload ────────────────────────────────────────────────────────────
+export const JWTPayloadSchema = z.object({
+    sub: z.string().min(1),
+    login: z.string().min(1),
+    name: z.string().min(1),
+    iat: z.number().int(),
+    exp: z.number().int(),
+    type: z.enum(["access", "refresh"]),
+});
+// ── SSHKeyPair ────────────────────────────────────────────────────────────
+export const SSHKeyPairSchema = z.object({
+    publicKey: z.string().min(1),
+    privateKey: z.string().min(1),
+    fingerprint: z.string().min(1),
+    algorithm: z.string().min(1),
+    createdAt: z.string().datetime(),
+});
+// ── GitForgeConfig ────────────────────────────────────────────────────────
+export const GitForgeConfigSchema = z.object({
+    type: z.enum(["github", "gitlab", "bitbucket"]),
+    baseUrl: z.string().url(),
+    credentials: z.record(z.string(), z.string()),
+});
+// ── GitHubOAuthConfig ─────────────────────────────────────────────────────
+export const GitHubOAuthConfigSchema = z.object({
+    clientId: z.string().min(1),
+    clientSecret: z.string().min(1),
+    callbackUrl: z.string().url(),
+    scopes: z.array(z.string()),
+});
+// ── GitHubAppConfig ───────────────────────────────────────────────────────
+export const GitHubAppConfigSchema = z.object({
+    appId: z.string().min(1),
+    privateKey: z.string().min(1),
+    webhookSecret: z.string().optional(),
+});

package/dist/backend.d.ts

@@ -0,0 +1,248 @@
+import type { Breakpoint, BreakpointComment, BreakpointDependency, BreakpointPublicAnswer, BreakpointContext, BreakpointRouting, BreakpointStatus, BreakpointWaitResult, ResponderProfile, TaskPriority } from "./types.js";
+/**
+ * Parameters for submitting a new breakpoint to a backend.
+ */
+export interface SubmitBreakpointParams {
+    /** The breakpoint question text. */
+    text: string;
+    /** Rich context for the breakpoint. */
+    context: BreakpointContext;
+    /** Routing configuration. */
+    routing: BreakpointRouting;
+    /** Optional task-management priority. */
+    priority?: TaskPriority;
+    /** Optional dependency list that can block completion. */
+    dependsOn?: BreakpointDependency[];
+    /** Whether the requester requires a signed answer. */
+    proven?: boolean;
+    /** Optional project scope. */
+    projectId?: string;
+    /** Optional repository scope. */
+    repoId?: string;
+}
+/**
+ * Options for waiting for an answer from a backend.
+ */
+export interface WaitForAnswerOptions {
+    /** Maximum time to wait in milliseconds. */
+    timeoutMs?: number;
+    /** Polling interval in milliseconds (for polling-based backends). */
+    pollIntervalMs?: number;
+    /** Whether to prefer event-based updates over polling. */
+    preferStreaming?: boolean;
+    /** AbortSignal for external cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Parameters for submitting an answer to a breakpoint.
+ */
+export interface SubmitAnswerParams {
+    /** ID of the responder submitting the answer. */
+    responderId: string;
+    /** Display name of the responder. */
+    responderName: string;
+    /** The answer text. */
+    text: string;
+    /** Whether the breakpoint action is approved (for approval-type breakpoints). */
+    approved?: boolean;
+    /** Confidence score 0-100. */
+    confidence?: number;
+    /** Reference links or file paths. */
+    references?: string[];
+    /** Follow-up questions to consider. */
+    followUpQuestions?: string[];
+    /** Decision memory for future reference. */
+    decisionMemory?: {
+        applicabilityContext: string;
+        reasoning: string;
+    };
+    /** Whether the responder explicitly requests signing. */
+    sign?: boolean;
+    /** Specific signing key fingerprint to use when signing. */
+    keyFingerprint?: string;
+}
+/**
+ * Options for listing responders.
+ */
+export interface ListRespondersParams {
+    projectId?: string;
+    repoId?: string;
+}
+export interface BreakpointBackendCapabilities {
+    search: boolean;
+    bulkOperations: boolean;
+    assignment: boolean;
+    comments: boolean;
+    history: boolean;
+    metrics: boolean;
+    export: boolean;
+    forms: boolean;
+    notifications: boolean;
+    escalation: boolean;
+}
+export interface BreakpointSearchQuery {
+    query?: string;
+    status?: BreakpointStatus[];
+    priority?: TaskPriority[];
+    assigneeId?: string;
+    responderId?: string;
+    tags?: string[];
+    domain?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+    updatedAfter?: string;
+    updatedBefore?: string;
+    sortBy?: "createdAt" | "updatedAt" | "priority" | "status";
+    sortDirection?: "asc" | "desc";
+    offset?: number;
+    limit?: number;
+}
+export interface SearchBreakpointsResult {
+    items: Breakpoint[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+export interface AssignBreakpointParams {
+    assigneeId: string;
+    assigneeName?: string;
+    actorId?: string;
+}
+export interface TransitionBreakpointParams {
+    status: BreakpointStatus;
+    actorId?: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AddBreakpointCommentParams {
+    authorId: string;
+    authorName?: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+export interface BulkUpdateBreakpointsParams {
+    ids: string[];
+    action: "approve" | "close" | "cancel" | "reassign" | "transition";
+    actorId?: string;
+    assigneeId?: string;
+    assigneeName?: string;
+    status?: BreakpointStatus;
+    answer?: SubmitAnswerParams;
+    message?: string;
+}
+export interface BulkUpdateBreakpointItemResult {
+    id: string;
+    ok: boolean;
+    breakpoint?: Breakpoint;
+    errorCode?: "not_found" | "invalid_transition" | "unsupported" | "error";
+    error?: string;
+}
+export interface BulkBreakpointOperationResult {
+    total: number;
+    succeeded: number;
+    failed: number;
+    items: BulkUpdateBreakpointItemResult[];
+}
+export interface BreakpointMetricsSummary {
+    total: number;
+    byStatus: Partial<Record<BreakpointStatus, number>>;
+    byPriority: Partial<Record<TaskPriority, number>>;
+    responseTimeAverageMs?: number;
+    completionTimeAverageMs?: number;
+}
+export interface BreakpointExport {
+    schemaVersion: 1;
+    exportedAt: string;
+    total: number;
+    items: Breakpoint[];
+}
+export declare class UnsupportedBreakpointFeatureError extends Error {
+    readonly backendName: string;
+    readonly feature: string;
+    constructor(backendName: string, feature: string);
+}
+export declare const unsupportedBreakpointBackendCapabilities: BreakpointBackendCapabilities;
+export declare function unsupportedBreakpointFeature(backendName: string, feature: string): never;
+/**
+ * Backend-agnostic interface for breakpoint lifecycle operations.
+ *
+ * Implementations may target different transports (git filesystem,
+ * HTTP server, GitHub Issues, etc.) while presenting a uniform API.
+ */
+export interface BreakpointBackend {
+    /** Human-readable name for this backend (e.g., "git-native", "server"). */
+    readonly name: string;
+    /**
+     * Submit a new breakpoint.
+     * Returns the created Breakpoint with a backend-assigned ID.
+     */
+    submitBreakpoint(params: SubmitBreakpointParams): Promise<Breakpoint>;
+    /**
+     * Retrieve a breakpoint by its ID.
+     */
+    getBreakpoint(id: string): Promise<Breakpoint>;
+    /**
+     * Wait for an answer to a breakpoint.
+     * Resolves when an answer arrives, the breakpoint reaches a terminal state,
+     * the timeout elapses, or the operation is aborted.
+     */
+    waitForAnswer(id: string, options?: WaitForAnswerOptions): Promise<BreakpointWaitResult>;
+    /**
+     * List pending breakpoints, optionally filtered by responder.
+     */
+    listPendingBreakpoints(responderId?: string): Promise<Breakpoint[]>;
+    /**
+     * Submit an answer for a breakpoint.
+     */
+    answerBreakpoint(id: string, answer: SubmitAnswerParams): Promise<BreakpointPublicAnswer>;
+    /**
+     * Cancel a pending breakpoint.
+     */
+    cancelBreakpoint(id: string): Promise<void>;
+    /**
+     * List available responder profiles.
+     * Optional -- backends that don't manage responder discovery may return [].
+     */
+    listResponders?(params?: ListRespondersParams): Promise<ResponderProfile[]>;
+    /**
+     * Claim a breakpoint, indicating intent to answer.
+     * Optional -- not all backends support explicit claiming.
+     */
+    claimBreakpoint?(id: string, responderId: string): Promise<Breakpoint>;
+    /**
+     * Report task-management capabilities supported by this backend.
+     */
+    capabilities?(): Promise<BreakpointBackendCapabilities> | BreakpointBackendCapabilities;
+    /**
+     * Search and filter breakpoints across lifecycle states.
+     */
+    searchBreakpoints?(query: BreakpointSearchQuery): Promise<SearchBreakpointsResult>;
+    /**
+     * Assign or reassign a breakpoint to a responder.
+     */
+    assignBreakpoint?(id: string, params: AssignBreakpointParams): Promise<Breakpoint>;
+    /**
+     * Transition a breakpoint through the validated task lifecycle.
+     */
+    transitionBreakpoint?(id: string, params: TransitionBreakpointParams): Promise<Breakpoint>;
+    /**
+     * Append a discussion comment to a breakpoint.
+     */
+    addBreakpointComment?(id: string, params: AddBreakpointCommentParams): Promise<BreakpointComment>;
+    /**
+     * Apply an operation to many breakpoints and report item-level outcomes.
+     */
+    bulkUpdateBreakpoints?(params: BulkUpdateBreakpointsParams): Promise<BulkBreakpointOperationResult>;
+    /**
+     * Compute deterministic metrics for matching breakpoints.
+     */
+    getBreakpointMetrics?(query?: BreakpointSearchQuery): Promise<BreakpointMetricsSummary>;
+    /**
+     * Export matching breakpoint data with credentials redacted.
+     */
+    exportBreakpoints?(query?: BreakpointSearchQuery): Promise<BreakpointExport>;
+}
+export declare function selectBreakpointAnswer(breakpoint: Pick<Breakpoint, "answers" | "selectedAnswer">): BreakpointPublicAnswer | undefined;
+export declare function supportsProvenAnswers(backendName: string): boolean;
+export declare function unsupportedBackendFeatureMessage(backendName: string, feature: string): string;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

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