git-workspace-service 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1518 @@
+/**
+ * Git Workspace Service Types
+ *
+ * Types for git workspace provisioning and credential management.
+ */
+type GitProvider = 'github' | 'gitlab' | 'bitbucket' | 'azure_devops' | 'self_hosted';
+type CredentialType = 'github_app' | 'oauth' | 'deploy_key' | 'pat' | 'ssh_key';
+/**
+ * Configuration for creating a new branch
+ */
+interface BranchConfig {
+    /**
+     * Execution or context ID this branch belongs to
+     */
+    executionId: string;
+    /**
+     * Role or task identifier
+     */
+    role: string;
+    /**
+     * Optional slug for human readability
+     */
+    slug?: string;
+    /**
+     * Base branch to create from
+     */
+    baseBranch: string;
+}
+/**
+ * Information about a created branch
+ */
+interface BranchInfo {
+    /**
+     * Full branch name (e.g., "parallax/exec-abc123/engineer-auth")
+     */
+    name: string;
+    /**
+     * Execution this branch belongs to
+     */
+    executionId: string;
+    /**
+     * Base branch it was created from
+     */
+    baseBranch: string;
+    /**
+     * When the branch was created
+     */
+    createdAt: Date;
+    /**
+     * Associated PR if one exists
+     */
+    pullRequest?: PullRequestInfo;
+}
+/**
+ * Token-based credentials (PAT or OAuth)
+ */
+interface TokenCredentials {
+    /**
+     * Type of credential
+     */
+    type: 'pat' | 'oauth';
+    /**
+     * The credential token
+     */
+    token: string;
+    /**
+     * Git provider this credential is for (defaults to 'github')
+     */
+    provider?: GitProvider;
+}
+/**
+ * SSH-based credentials using system SSH agent
+ */
+interface SshCredentials {
+    /**
+     * Type of credential
+     */
+    type: 'ssh';
+    /**
+     * Git provider this credential is for (defaults to 'github')
+     */
+    provider?: GitProvider;
+}
+/**
+ * User-provided credentials passed at execution time.
+ * Allows users to supply their own PAT, OAuth token, or use system SSH.
+ */
+type UserProvidedCredentials = TokenCredentials | SshCredentials;
+/**
+ * Context for credential requests (for audit trails)
+ */
+interface CredentialContext {
+    executionId: string;
+    taskId?: string;
+    agentId?: string;
+    userId?: string;
+    reason?: string;
+}
+/**
+ * Request for git credentials
+ */
+interface GitCredentialRequest {
+    /**
+     * Repository URL or identifier
+     */
+    repo: string;
+    /**
+     * Required access level
+     */
+    access: 'read' | 'write';
+    /**
+     * Context for audit trail
+     */
+    context: CredentialContext;
+    /**
+     * Requested TTL in seconds (max enforced by policy)
+     */
+    ttlSeconds?: number;
+    /**
+     * User-provided credentials (PAT or OAuth token)
+     * If provided, these are used instead of managed credentials
+     */
+    userProvided?: UserProvidedCredentials;
+}
+/**
+ * A git credential grant
+ */
+interface GitCredential {
+    /**
+     * Unique ID for this credential grant
+     */
+    id: string;
+    /**
+     * How to authenticate
+     */
+    type: CredentialType;
+    /**
+     * The credential value (token, key, etc.)
+     */
+    token: string;
+    /**
+     * Repository this credential is scoped to
+     */
+    repo: string;
+    /**
+     * Permissions granted
+     */
+    permissions: string[];
+    /**
+     * When this credential expires
+     */
+    expiresAt: Date;
+    /**
+     * Git provider
+     */
+    provider: GitProvider;
+}
+/**
+ * Record of a credential grant for auditing
+ */
+interface CredentialGrant {
+    id: string;
+    type: CredentialType;
+    repo: string;
+    provider: GitProvider;
+    grantedTo: {
+        executionId: string;
+        taskId?: string;
+        agentId?: string;
+    };
+    permissions: string[];
+    createdAt: Date;
+    expiresAt: Date;
+    revokedAt?: Date;
+    lastUsedAt?: Date;
+}
+type BranchStrategy = 'feature_branch' | 'fork' | 'direct';
+type WorkspaceStatus = 'provisioning' | 'ready' | 'in_use' | 'finalizing' | 'cleaned_up' | 'error';
+/**
+ * Configuration for provisioning a workspace
+ */
+interface WorkspaceConfig {
+    /**
+     * Repository to clone
+     */
+    repo: string;
+    /**
+     * Git provider
+     */
+    provider?: GitProvider;
+    /**
+     * Branch strategy
+     */
+    branchStrategy: BranchStrategy;
+    /**
+     * Base branch to create feature branches from
+     */
+    baseBranch: string;
+    /**
+     * Execution context
+     */
+    execution: {
+        id: string;
+        patternName: string;
+    };
+    /**
+     * Task/role requesting the workspace
+     */
+    task: {
+        id: string;
+        role: string;
+        slug?: string;
+    };
+    /**
+     * User context for credential resolution
+     */
+    user?: {
+        id: string;
+        oauthToken?: string;
+    };
+    /**
+     * User-provided credentials (PAT or OAuth token)
+     * If provided, these are used instead of managed credentials
+     */
+    userCredentials?: UserProvidedCredentials;
+}
+/**
+ * A provisioned git workspace
+ */
+interface Workspace {
+    /**
+     * Unique workspace ID
+     */
+    id: string;
+    /**
+     * Local filesystem path
+     */
+    path: string;
+    /**
+     * Repository URL
+     */
+    repo: string;
+    /**
+     * Branch created for this workspace
+     */
+    branch: BranchInfo;
+    /**
+     * Credential for this workspace
+     */
+    credential: GitCredential;
+    /**
+     * When the workspace was provisioned
+     */
+    provisionedAt: Date;
+    /**
+     * Current status
+     */
+    status: WorkspaceStatus;
+}
+/**
+ * Options for finalizing a workspace (push, PR creation, cleanup)
+ */
+interface WorkspaceFinalization {
+    /**
+     * Whether to push the branch
+     */
+    push: boolean;
+    /**
+     * Whether to create a PR
+     */
+    createPr: boolean;
+    /**
+     * PR configuration
+     */
+    pr?: {
+        title: string;
+        body: string;
+        targetBranch: string;
+        draft?: boolean;
+        labels?: string[];
+        reviewers?: string[];
+    };
+    /**
+     * Whether to clean up the workspace after finalization
+     */
+    cleanup: boolean;
+}
+/**
+ * Information about a pull request
+ */
+interface PullRequestInfo {
+    /**
+     * PR number
+     */
+    number: number;
+    /**
+     * PR URL
+     */
+    url: string;
+    /**
+     * PR state
+     */
+    state: 'open' | 'closed' | 'merged';
+    /**
+     * Source branch
+     */
+    sourceBranch: string;
+    /**
+     * Target branch
+     */
+    targetBranch: string;
+    /**
+     * Title
+     */
+    title: string;
+    /**
+     * Associated execution ID
+     */
+    executionId: string;
+    /**
+     * Created timestamp
+     */
+    createdAt: Date;
+    /**
+     * Merged timestamp if merged
+     */
+    mergedAt?: Date;
+}
+/**
+ * Issue state
+ */
+type IssueState = 'open' | 'closed';
+/**
+ * Information about an issue
+ */
+interface IssueInfo {
+    /**
+     * Issue number
+     */
+    number: number;
+    /**
+     * Issue URL
+     */
+    url: string;
+    /**
+     * Issue state
+     */
+    state: IssueState;
+    /**
+     * Issue title
+     */
+    title: string;
+    /**
+     * Issue body/description
+     */
+    body: string;
+    /**
+     * Labels on the issue
+     */
+    labels: string[];
+    /**
+     * Assignees
+     */
+    assignees: string[];
+    /**
+     * Created timestamp
+     */
+    createdAt: Date;
+    /**
+     * Closed timestamp if closed
+     */
+    closedAt?: Date;
+    /**
+     * Associated execution ID (if managed)
+     */
+    executionId?: string;
+}
+/**
+ * Options for creating an issue
+ */
+interface CreateIssueOptions {
+    /**
+     * Issue title
+     */
+    title: string;
+    /**
+     * Issue body/description
+     */
+    body: string;
+    /**
+     * Labels to add
+     */
+    labels?: string[];
+    /**
+     * Assignees (usernames)
+     */
+    assignees?: string[];
+    /**
+     * Milestone number
+     */
+    milestone?: number;
+}
+/**
+ * Options for commenting on an issue
+ */
+interface IssueCommentOptions {
+    /**
+     * Comment body
+     */
+    body: string;
+}
+/**
+ * Information about an issue comment
+ */
+interface IssueComment {
+    /**
+     * Comment ID
+     */
+    id: number;
+    /**
+     * Comment URL
+     */
+    url: string;
+    /**
+     * Comment body
+     */
+    body: string;
+    /**
+     * Author username
+     */
+    author: string;
+    /**
+     * Created timestamp
+     */
+    createdAt: Date;
+}
+/**
+ * Permission level for a resource
+ */
+type PermissionLevel = 'none' | 'read' | 'write';
+/**
+ * Repository access scope
+ */
+type RepositoryScope = {
+    type: 'all';
+} | {
+    type: 'public';
+} | {
+    type: 'selected';
+    repos: string[];
+};
+/**
+ * Permissions that an agent can request/receive.
+ * Designed to be restrictive by default - dangerous operations require explicit opt-in.
+ */
+interface AgentPermissions {
+    /**
+     * Which repositories the agent can access
+     */
+    repositories: RepositoryScope;
+    /**
+     * Permission for repository contents (code, files)
+     */
+    contents: PermissionLevel;
+    /**
+     * Permission for pull requests
+     */
+    pullRequests: PermissionLevel;
+    /**
+     * Permission for issues
+     */
+    issues: PermissionLevel;
+    /**
+     * Permission for metadata (repo info, branches, tags)
+     */
+    metadata: PermissionLevel;
+    /**
+     * Can delete branches (for cleanup after merge)
+     * @default false
+     */
+    canDeleteBranch?: boolean;
+    /**
+     * Can force push to branches
+     * @default false - Almost never needed, can destroy history
+     */
+    canForcePush?: boolean;
+    /**
+     * Can delete repositories
+     * @default false - Should NEVER be true for agents
+     */
+    canDeleteRepository?: boolean;
+    /**
+     * Can modify repository settings/webhooks
+     * @default false
+     */
+    canAdminister?: boolean;
+}
+/**
+ * Default safe permissions for agents
+ */
+declare const DEFAULT_AGENT_PERMISSIONS: AgentPermissions;
+/**
+ * Read-only permissions for agents that only need to inspect
+ */
+declare const READONLY_AGENT_PERMISSIONS: AgentPermissions;
+/**
+ * OAuth token with metadata
+ */
+interface OAuthToken {
+    /**
+     * Access token for API calls
+     */
+    accessToken: string;
+    /**
+     * Token type (usually "bearer")
+     */
+    tokenType: string;
+    /**
+     * Scopes granted by the token
+     */
+    scopes: string[];
+    /**
+     * When the token expires
+     */
+    expiresAt?: Date;
+    /**
+     * Refresh token for obtaining new access tokens
+     */
+    refreshToken?: string;
+    /**
+     * Provider this token is for
+     */
+    provider: GitProvider;
+    /**
+     * Permissions associated with this token
+     */
+    permissions: AgentPermissions;
+    /**
+     * When the token was created
+     */
+    createdAt: Date;
+}
+/**
+ * Device code response from OAuth provider
+ */
+interface DeviceCodeResponse {
+    /**
+     * Code to poll for authorization
+     */
+    deviceCode: string;
+    /**
+     * Code for user to enter
+     */
+    userCode: string;
+    /**
+     * URL for user to visit
+     */
+    verificationUri: string;
+    /**
+     * Full URL with code pre-filled (if supported)
+     */
+    verificationUriComplete?: string;
+    /**
+     * Seconds until codes expire
+     */
+    expiresIn: number;
+    /**
+     * Seconds between poll requests
+     */
+    interval: number;
+}
+/**
+ * Auth prompt for user interaction
+ */
+interface AuthPrompt {
+    /**
+     * Provider requiring auth
+     */
+    provider: GitProvider;
+    /**
+     * URL to visit
+     */
+    verificationUri: string;
+    /**
+     * Code to enter
+     */
+    userCode: string;
+    /**
+     * Seconds until code expires
+     */
+    expiresIn: number;
+    /**
+     * Permissions being requested
+     */
+    requestedPermissions: AgentPermissions;
+}
+/**
+ * Result of auth flow
+ */
+interface AuthResult {
+    /**
+     * Whether auth succeeded
+     */
+    success: boolean;
+    /**
+     * Provider that was authenticated
+     */
+    provider: GitProvider;
+    /**
+     * Username/identity if successful
+     */
+    username?: string;
+    /**
+     * Error message if failed
+     */
+    error?: string;
+}
+/**
+ * Callback interface for auth prompts
+ */
+interface AuthPromptEmitter {
+    /**
+     * Called when user action is required for authentication
+     */
+    onAuthRequired(prompt: AuthPrompt): void;
+    /**
+     * Called when authentication completes (success or failure)
+     */
+    onAuthComplete(result: AuthResult): void;
+    /**
+     * Called periodically while waiting for auth (optional)
+     */
+    onAuthPending?(secondsRemaining: number): void;
+}
+/**
+ * GitHub App configuration
+ */
+interface GitHubAppConfig {
+    appId: string;
+    privateKey: string;
+    webhookSecret?: string;
+}
+/**
+ * GitHub App installation info
+ */
+interface GitHubAppInstallation {
+    installationId: number;
+    accountLogin: string;
+    accountType: 'User' | 'Organization';
+    repositories: string[];
+    permissions: Record<string, string>;
+}
+/**
+ * Configuration for the workspace service
+ */
+interface WorkspaceServiceConfig {
+    /**
+     * Base directory for workspace storage
+     */
+    baseDir: string;
+    /**
+     * Default TTL for credentials in seconds
+     */
+    defaultCredentialTtl?: number;
+    /**
+     * Maximum TTL for credentials in seconds
+     */
+    maxCredentialTtl?: number;
+    /**
+     * Default branch naming prefix
+     */
+    branchPrefix?: string;
+    /**
+     * GitHub App configuration (optional)
+     */
+    githubApp?: GitHubAppConfig;
+}
+/**
+ * Configuration for the credential service
+ */
+interface CredentialServiceConfig {
+    /**
+     * Default TTL for credentials in seconds
+     */
+    defaultTtl?: number;
+    /**
+     * Maximum TTL for credentials in seconds
+     */
+    maxTtl?: number;
+    /**
+     * GitHub App configuration
+     */
+    githubApp?: GitHubAppConfig;
+}
+/**
+ * Interface for git provider implementations
+ */
+interface GitProviderAdapter {
+    /**
+     * Provider name
+     */
+    readonly name: GitProvider;
+    /**
+     * Get credentials for a repository
+     */
+    getCredentials(request: GitCredentialRequest): Promise<GitCredential>;
+    /**
+     * Revoke a credential
+     */
+    revokeCredential(credentialId: string): Promise<void>;
+    /**
+     * Create a pull request
+     */
+    createPullRequest(options: {
+        repo: string;
+        sourceBranch: string;
+        targetBranch: string;
+        title: string;
+        body: string;
+        draft?: boolean;
+        labels?: string[];
+        reviewers?: string[];
+        credential: GitCredential;
+    }): Promise<PullRequestInfo>;
+    /**
+     * Check if a branch exists
+     */
+    branchExists(repo: string, branch: string, credential: GitCredential): Promise<boolean>;
+    /**
+     * Get the default branch for a repository
+     */
+    getDefaultBranch(repo: string, credential: GitCredential): Promise<string>;
+}
+type WorkspaceEventType = 'workspace:provisioning' | 'workspace:ready' | 'workspace:error' | 'workspace:finalizing' | 'workspace:cleaned_up' | 'credential:granted' | 'credential:revoked' | 'pr:created' | 'pr:merged';
+interface WorkspaceEvent {
+    type: WorkspaceEventType;
+    workspaceId?: string;
+    credentialId?: string;
+    executionId: string;
+    timestamp: Date;
+    data?: Record<string, unknown>;
+    error?: string;
+}
+type WorkspaceEventHandler = (event: WorkspaceEvent) => void | Promise<void>;
+
+/**
+ * OAuth Device Code Flow
+ *
+ * Implements the OAuth 2.0 Device Authorization Grant (RFC 8628)
+ * for authenticating CLI/agent applications without browser control.
+ *
+ * Flow:
+ * 1. Request device code from provider
+ * 2. Display verification URL and user code to user
+ * 3. Poll for authorization while user completes in browser
+ * 4. Receive access token on success
+ */
+
+interface OAuthDeviceFlowConfig {
+    /**
+     * OAuth Client ID
+     */
+    clientId: string;
+    /**
+     * OAuth Client Secret (optional for public clients)
+     */
+    clientSecret?: string;
+    /**
+     * Provider (defaults to 'github')
+     */
+    provider?: GitProvider;
+    /**
+     * Permissions to request
+     */
+    permissions?: AgentPermissions;
+    /**
+     * Auth prompt emitter for user interaction
+     */
+    promptEmitter?: AuthPromptEmitter;
+    /**
+     * Timeout in seconds for the auth flow (default: 900 = 15 min)
+     */
+    timeout?: number;
+}
+interface OAuthDeviceFlowLogger {
+    info(data: Record<string, unknown>, message: string): void;
+    warn(data: Record<string, unknown>, message: string): void;
+    error(data: Record<string, unknown>, message: string): void;
+    debug(data: Record<string, unknown>, message: string): void;
+}
+/**
+ * OAuth Device Code Flow implementation for GitHub
+ */
+declare class OAuthDeviceFlow {
+    private readonly clientId;
+    private readonly clientSecret?;
+    private readonly provider;
+    private readonly permissions;
+    private readonly promptEmitter?;
+    private readonly timeout;
+    private readonly logger?;
+    constructor(config: OAuthDeviceFlowConfig, logger?: OAuthDeviceFlowLogger);
+    /**
+     * Start the device code flow and wait for authorization
+     */
+    authorize(): Promise<OAuthToken>;
+    /**
+     * Request a device code from GitHub
+     */
+    requestDeviceCode(): Promise<DeviceCodeResponse>;
+    /**
+     * Poll for the access token until authorized or timeout
+     */
+    pollForToken(deviceCode: DeviceCodeResponse): Promise<OAuthToken>;
+    /**
+     * Exchange device code for access token
+     */
+    private exchangeDeviceCode;
+    /**
+     * Refresh an expired token
+     */
+    refreshToken(refreshTokenValue: string): Promise<OAuthToken>;
+    /**
+     * Convert AgentPermissions to GitHub OAuth scopes
+     */
+    private permissionsToScopes;
+    /**
+     * Print auth prompt to console (default behavior)
+     */
+    private printAuthPrompt;
+    private sleep;
+    private log;
+}
+
+/**
+ * Token Store
+ *
+ * Securely stores and manages OAuth tokens with support for:
+ * - Expiry checking
+ * - Automatic refresh triggers
+ * - Multiple storage backends (file, memory, keychain)
+ */
+
+interface TokenStoreOptions {
+    /**
+     * Encryption key for file-based storage
+     * If not provided, tokens are stored in plaintext (not recommended for production)
+     */
+    encryptionKey?: string;
+    /**
+     * Directory to store tokens (for FileTokenStore)
+     * Default: ~/.parallax/tokens
+     */
+    directory?: string;
+}
+/**
+ * Token store interface
+ */
+declare abstract class TokenStore {
+    /**
+     * Save a token for a provider
+     */
+    abstract save(provider: GitProvider, token: OAuthToken): Promise<void>;
+    /**
+     * Get a token for a provider
+     */
+    abstract get(provider: GitProvider): Promise<OAuthToken | null>;
+    /**
+     * Clear a token for a provider (or all tokens)
+     */
+    abstract clear(provider?: GitProvider): Promise<void>;
+    /**
+     * List all stored providers
+     */
+    abstract list(): Promise<GitProvider[]>;
+    /**
+     * Check if a token is expired
+     */
+    isExpired(token: OAuthToken): boolean;
+    /**
+     * Check if a token needs refresh (expired or close to expiry)
+     */
+    needsRefresh(token: OAuthToken): boolean;
+}
+/**
+ * In-memory token store (for testing and short-lived processes)
+ */
+declare class MemoryTokenStore extends TokenStore {
+    private tokens;
+    save(provider: GitProvider, token: OAuthToken): Promise<void>;
+    get(provider: GitProvider): Promise<OAuthToken | null>;
+    clear(provider?: GitProvider): Promise<void>;
+    list(): Promise<GitProvider[]>;
+}
+/**
+ * File-based token store with optional encryption
+ */
+declare class FileTokenStore extends TokenStore {
+    private readonly directory;
+    private readonly encryptionKey?;
+    constructor(options?: TokenStoreOptions);
+    save(provider: GitProvider, token: OAuthToken): Promise<void>;
+    get(provider: GitProvider): Promise<OAuthToken | null>;
+    clear(provider?: GitProvider): Promise<void>;
+    list(): Promise<GitProvider[]>;
+    private getTokenPath;
+    private ensureDirectory;
+    private encrypt;
+    private decrypt;
+}
+
+/**
+ * Git Credential Service
+ *
+ * Manages credentials for private repository access.
+ * Supports GitHub App, OAuth device flow, deploy keys, and PATs.
+ *
+ * Credential priority:
+ * 1. User-provided (PAT, OAuth token, SSH)
+ * 2. Cached OAuth token (from TokenStore)
+ * 3. Provider adapter (GitHub App, etc.)
+ * 4. OAuth device flow (interactive)
+ */
+
+interface CredentialServiceLogger {
+    info(data: Record<string, unknown>, message: string): void;
+    warn(data: Record<string, unknown>, message: string): void;
+    error(data: Record<string, unknown>, message: string): void;
+}
+interface CredentialGrantStore {
+    create(grant: CredentialGrant & {
+        reason?: string;
+    }): Promise<void>;
+    findById(id: string): Promise<CredentialGrant | null>;
+    findByExecutionId(executionId: string): Promise<CredentialGrant[]>;
+    revoke(id: string): Promise<void>;
+    revokeForExecution(executionId: string): Promise<number>;
+}
+interface OAuthConfig {
+    /**
+     * OAuth Client ID (required for device flow)
+     */
+    clientId: string;
+    /**
+     * OAuth Client Secret (optional for public clients)
+     */
+    clientSecret?: string;
+    /**
+     * Default permissions to request
+     */
+    permissions?: AgentPermissions;
+    /**
+     * Callback for auth prompts (for PTY integration)
+     */
+    promptEmitter?: AuthPromptEmitter;
+}
+interface CredentialServiceOptions {
+    /**
+     * Default TTL for credentials in seconds
+     */
+    defaultTtlSeconds?: number;
+    /**
+     * Maximum TTL allowed
+     */
+    maxTtlSeconds?: number;
+    /**
+     * Provider adapters keyed by provider name
+     */
+    providers?: Map<GitProvider, GitProviderAdapter>;
+    /**
+     * Optional persistent store for grants
+     */
+    grantStore?: CredentialGrantStore;
+    /**
+     * Token store for cached OAuth tokens
+     * Default: MemoryTokenStore
+     */
+    tokenStore?: TokenStore;
+    /**
+     * OAuth configuration for device flow authentication
+     * If provided, enables interactive OAuth as a fallback
+     */
+    oauth?: OAuthConfig;
+    /**
+     * Optional logger
+     */
+    logger?: CredentialServiceLogger;
+}
+declare class CredentialService {
+    private grants;
+    private readonly defaultTtl;
+    private readonly maxTtl;
+    private readonly providers;
+    private readonly grantStore?;
+    private readonly tokenStore;
+    private readonly oauthConfig?;
+    private readonly logger?;
+    constructor(options?: CredentialServiceOptions);
+    /**
+     * Get the token store (for external access to cached tokens)
+     */
+    getTokenStore(): TokenStore;
+    /**
+     * Register a provider adapter
+     */
+    registerProvider(provider: GitProviderAdapter): void;
+    /**
+     * Get a provider adapter
+     */
+    getProvider(name: GitProvider): GitProviderAdapter | undefined;
+    /**
+     * Request credentials for a repository
+     */
+    getCredentials(request: GitCredentialRequest): Promise<GitCredential>;
+    /**
+     * Revoke a credential grant
+     */
+    revokeCredential(grantId: string): Promise<void>;
+    /**
+     * Revoke all credentials for an execution
+     */
+    revokeForExecution(executionId: string): Promise<number>;
+    /**
+     * Check if a credential is valid
+     */
+    isValid(grantId: string): boolean;
+    /**
+     * Get grant info for audit
+     */
+    getGrant(grantId: string): Promise<CredentialGrant | null>;
+    /**
+     * List all grants for an execution
+     */
+    getGrantsForExecution(executionId: string): Promise<CredentialGrant[]>;
+    private detectProvider;
+    /**
+     * Create a GitCredential from user-provided credentials (PAT or OAuth token)
+     */
+    private createUserProvidedCredential;
+    /**
+     * Check for a cached OAuth token and create credential from it
+     */
+    private getCachedOAuthCredential;
+    /**
+     * Initiate interactive OAuth device flow
+     */
+    private getOAuthCredentialViaDeviceFlow;
+    /**
+     * Refresh an OAuth token
+     */
+    private refreshOAuthToken;
+    /**
+     * Create a GitCredential from an OAuthToken
+     */
+    private createOAuthCredential;
+    private log;
+}
+
+/**
+ * Workspace Service
+ *
+ * Provisions and manages git workspaces for agent tasks.
+ * Handles cloning, branching, and PR creation.
+ */
+
+interface WorkspaceServiceLogger {
+    info(data: Record<string, unknown>, message: string): void;
+    warn(data: Record<string, unknown>, message: string): void;
+    error(data: Record<string, unknown>, message: string): void;
+    debug(data: Record<string, unknown>, message: string): void;
+}
+interface WorkspaceServiceOptions {
+    /**
+     * Configuration
+     */
+    config: WorkspaceServiceConfig;
+    /**
+     * Credential service for managing git credentials
+     */
+    credentialService: CredentialService;
+    /**
+     * Optional logger
+     */
+    logger?: WorkspaceServiceLogger;
+}
+declare class WorkspaceService {
+    private workspaces;
+    private readonly baseDir;
+    private readonly branchPrefix;
+    private readonly credentialService;
+    private readonly logger?;
+    private readonly eventHandlers;
+    constructor(options: WorkspaceServiceOptions);
+    /**
+     * Initialize the workspace service
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register an event handler
+     */
+    onEvent(handler: WorkspaceEventHandler): () => void;
+    /**
+     * Provision a new workspace for a task
+     */
+    provision(config: WorkspaceConfig): Promise<Workspace>;
+    /**
+     * Finalize a workspace (push, create PR, cleanup)
+     */
+    finalize(workspaceId: string, options: WorkspaceFinalization): Promise<PullRequestInfo | void>;
+    /**
+     * Get a workspace by ID
+     */
+    get(workspaceId: string): Workspace | null;
+    /**
+     * Get all workspaces for an execution
+     */
+    getForExecution(executionId: string): Workspace[];
+    /**
+     * Clean up a workspace
+     */
+    cleanup(workspaceId: string): Promise<void>;
+    /**
+     * Clean up all workspaces for an execution
+     */
+    cleanupForExecution(executionId: string): Promise<void>;
+    private cloneRepo;
+    private createBranch;
+    private configureGit;
+    private pushBranch;
+    private createPullRequest;
+    private parseRepo;
+    private buildAuthenticatedUrl;
+    private execInDir;
+    private log;
+    private emitEvent;
+}
+
+/**
+ * GitHub Provider
+ *
+ * Handles GitHub App authentication and API operations.
+ * Requires @octokit/rest and @octokit/auth-app as peer dependencies.
+ */
+
+interface GitHubProviderConfig {
+    /**
+     * GitHub App ID
+     */
+    appId: string;
+    /**
+     * GitHub App private key (PEM format)
+     */
+    privateKey: string;
+    /**
+     * Webhook secret for verifying webhooks
+     */
+    webhookSecret?: string;
+    /**
+     * GitHub API base URL (for GitHub Enterprise)
+     */
+    baseUrl?: string;
+}
+interface GitHubProviderLogger {
+    info(data: Record<string, unknown>, message: string): void;
+    warn(data: Record<string, unknown>, message: string): void;
+    error(data: Record<string, unknown>, message: string): void;
+    debug(data: Record<string, unknown>, message: string): void;
+}
+declare class GitHubProvider implements GitProviderAdapter {
+    private readonly config;
+    private readonly logger?;
+    readonly name: "github";
+    private appOctokit;
+    private installations;
+    private installationOctokits;
+    private initialized;
+    constructor(config: GitHubProviderConfig, logger?: GitHubProviderLogger | undefined);
+    /**
+     * Initialize provider - fetch all installations
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register an installation (called on webhook or init)
+     */
+    registerInstallation(installationId: number): Promise<GitHubAppInstallation>;
+    /**
+     * Get installation for a repository
+     */
+    getInstallationForRepo(owner: string, repo: string): GitHubAppInstallation | null;
+    /**
+     * Get credentials for a repository (implements GitProviderAdapter)
+     */
+    getCredentials(request: GitCredentialRequest): Promise<GitCredential>;
+    /**
+     * Get credentials for a repository by owner/repo
+     */
+    getCredentialsForRepo(owner: string, repo: string, access: 'read' | 'write', ttlSeconds?: number): Promise<GitCredential>;
+    /**
+     * Revoke a credential (no-op for GitHub App tokens - they expire automatically)
+     */
+    revokeCredential(_credentialId: string): Promise<void>;
+    /**
+     * Create a pull request (implements GitProviderAdapter)
+     */
+    createPullRequest(options: {
+        repo: string;
+        sourceBranch: string;
+        targetBranch: string;
+        title: string;
+        body: string;
+        draft?: boolean;
+        labels?: string[];
+        reviewers?: string[];
+        credential: GitCredential;
+    }): Promise<PullRequestInfo>;
+    /**
+     * Create a pull request by owner/repo
+     */
+    createPullRequestForRepo(owner: string, repo: string, options: {
+        title: string;
+        body: string;
+        head: string;
+        base: string;
+        draft?: boolean;
+        labels?: string[];
+        reviewers?: string[];
+    }): Promise<PullRequestInfo>;
+    /**
+     * Check if a branch exists (implements GitProviderAdapter)
+     */
+    branchExists(repo: string, branch: string, _credential: GitCredential): Promise<boolean>;
+    /**
+     * Get the default branch for a repository (implements GitProviderAdapter)
+     */
+    getDefaultBranch(repo: string, _credential: GitCredential): Promise<string>;
+    /**
+     * Get pull request status
+     */
+    getPullRequest(owner: string, repo: string, prNumber: number): Promise<PullRequestInfo>;
+    /**
+     * Delete a branch
+     */
+    deleteBranch(owner: string, repo: string, branch: string): Promise<void>;
+    /**
+     * List all managed branches for a repo
+     */
+    listManagedBranches(owner: string, repo: string, prefix?: string): Promise<string[]>;
+    /**
+     * Create an issue
+     */
+    createIssue(owner: string, repo: string, options: CreateIssueOptions): Promise<IssueInfo>;
+    /**
+     * Get an issue by number
+     */
+    getIssue(owner: string, repo: string, issueNumber: number): Promise<IssueInfo>;
+    /**
+     * List issues with optional filters
+     */
+    listIssues(owner: string, repo: string, options?: {
+        state?: IssueState | 'all';
+        labels?: string[];
+        assignee?: string;
+        since?: Date;
+    }): Promise<IssueInfo[]>;
+    /**
+     * Update an issue (labels, state, assignees, etc.)
+     */
+    updateIssue(owner: string, repo: string, issueNumber: number, options: {
+        title?: string;
+        body?: string;
+        state?: IssueState;
+        labels?: string[];
+        assignees?: string[];
+    }): Promise<IssueInfo>;
+    /**
+     * Add labels to an issue
+     */
+    addLabels(owner: string, repo: string, issueNumber: number, labels: string[]): Promise<void>;
+    /**
+     * Remove a label from an issue
+     */
+    removeLabel(owner: string, repo: string, issueNumber: number, label: string): Promise<void>;
+    /**
+     * Add a comment to an issue
+     */
+    addComment(owner: string, repo: string, issueNumber: number, options: IssueCommentOptions): Promise<IssueComment>;
+    /**
+     * List comments on an issue
+     */
+    listComments(owner: string, repo: string, issueNumber: number): Promise<IssueComment[]>;
+    /**
+     * Close an issue
+     */
+    closeIssue(owner: string, repo: string, issueNumber: number): Promise<IssueInfo>;
+    /**
+     * Reopen an issue
+     */
+    reopenIssue(owner: string, repo: string, issueNumber: number): Promise<IssueInfo>;
+    private getInstallationOctokit;
+    private parseRepo;
+    private log;
+}
+
+/**
+ * GitHub PAT Client
+ *
+ * Simple GitHub API client using a Personal Access Token.
+ * Useful for testing and simple integrations without GitHub App setup.
+ */
+
+interface GitHubPatClientOptions {
+    /**
+     * Personal Access Token
+     */
+    token: string;
+    /**
+     * GitHub API base URL (for GitHub Enterprise)
+     */
+    baseUrl?: string;
+}
+interface GitHubPatClientLogger {
+    info(data: Record<string, unknown>, message: string): void;
+    warn(data: Record<string, unknown>, message: string): void;
+    error(data: Record<string, unknown>, message: string): void;
+}
+/**
+ * Simple GitHub client using a Personal Access Token.
+ * Provides PR and Issue management without GitHub App complexity.
+ */
+declare class GitHubPatClient {
+    private octokit;
+    private readonly logger?;
+    constructor(options: GitHubPatClientOptions, logger?: GitHubPatClientLogger);
+    /**
+     * Create a pull request
+     */
+    createPullRequest(owner: string, repo: string, options: {
+        title: string;
+        body: string;
+        head: string;
+        base: string;
+        draft?: boolean;
+        labels?: string[];
+        reviewers?: string[];
+    }): Promise<PullRequestInfo>;
+    /**
+     * Get a pull request
+     */
+    getPullRequest(owner: string, repo: string, prNumber: number): Promise<PullRequestInfo>;
+    /**
+     * Create an issue
+     */
+    createIssue(owner: string, repo: string, options: CreateIssueOptions): Promise<IssueInfo>;
+    /**
+     * Get an issue
+     */
+    getIssue(owner: string, repo: string, issueNumber: number): Promise<IssueInfo>;
+    /**
+     * List issues
+     */
+    listIssues(owner: string, repo: string, options?: {
+        state?: IssueState | 'all';
+        labels?: string[];
+        assignee?: string;
+    }): Promise<IssueInfo[]>;
+    /**
+     * Update an issue
+     */
+    updateIssue(owner: string, repo: string, issueNumber: number, options: {
+        title?: string;
+        body?: string;
+        state?: IssueState;
+        labels?: string[];
+        assignees?: string[];
+    }): Promise<IssueInfo>;
+    /**
+     * Add labels to an issue
+     */
+    addLabels(owner: string, repo: string, issueNumber: number, labels: string[]): Promise<void>;
+    /**
+     * Remove a label from an issue
+     */
+    removeLabel(owner: string, repo: string, issueNumber: number, label: string): Promise<void>;
+    /**
+     * Add a comment to an issue or PR
+     */
+    addComment(owner: string, repo: string, issueNumber: number, options: IssueCommentOptions): Promise<IssueComment>;
+    /**
+     * List comments on an issue or PR
+     */
+    listComments(owner: string, repo: string, issueNumber: number): Promise<IssueComment[]>;
+    /**
+     * Close an issue
+     */
+    closeIssue(owner: string, repo: string, issueNumber: number): Promise<IssueInfo>;
+    /**
+     * Reopen an issue
+     */
+    reopenIssue(owner: string, repo: string, issueNumber: number): Promise<IssueInfo>;
+    /**
+     * Delete a branch
+     */
+    deleteBranch(owner: string, repo: string, branch: string): Promise<void>;
+    /**
+     * Check if a branch exists
+     */
+    branchExists(owner: string, repo: string, branch: string): Promise<boolean>;
+    private mapIssue;
+    private log;
+}
+
+/**
+ * Branch Naming Service
+ *
+ * Generates and parses managed branch names.
+ * Format: {prefix}/{execution-id}/{role}-{slug}
+ */
+
+declare const DEFAULT_BRANCH_PREFIX = "parallax";
+interface BranchNamingOptions {
+    /**
+     * Maximum length for the slug portion
+     */
+    maxSlugLength?: number;
+    /**
+     * Custom prefix (defaults to 'parallax')
+     */
+    prefix?: string;
+}
+/**
+ * Generate a branch name from configuration
+ */
+declare function generateBranchName(config: BranchConfig, options?: BranchNamingOptions): string;
+/**
+ * Parse a branch name into its components
+ */
+declare function parseBranchName(branchName: string, options?: BranchNamingOptions): {
+    executionId: string;
+    role: string;
+    slug?: string;
+} | null;
+/**
+ * Check if a branch name is a managed branch
+ */
+declare function isManagedBranch(branchName: string, options?: BranchNamingOptions): boolean;
+/**
+ * Get all branches for a specific execution
+ */
+declare function filterBranchesByExecution(branches: string[], executionId: string, options?: BranchNamingOptions): string[];
+/**
+ * Generate branch info object
+ */
+declare function createBranchInfo(config: BranchConfig, options?: BranchNamingOptions): BranchInfo;
+/**
+ * Generate a slug from a task description
+ */
+declare function generateSlug(description: string, maxLength?: number): string;
+
+/**
+ * Git Credential Helper
+ *
+ * This module provides a Git credential helper that integrates with the
+ * workspace service. It can be used in two modes:
+ *
+ * 1. Script mode: Run as a standalone script that Git calls
+ * 2. Embedded mode: Used within the workspace service to configure git
+ *
+ * Git credential helpers receive input on stdin in the format:
+ *   protocol=https
+ *   host=github.com
+ *   path=owner/repo
+ *
+ * And respond with:
+ *   username=x-access-token
+ *   password=<token>
+ */
+/**
+ * Credential context stored per-workspace
+ * This is written to a file that the helper reads
+ */
+interface CredentialHelperContext {
+    workspaceId: string;
+    executionId: string;
+    repo: string;
+    token: string;
+    expiresAt: string;
+}
+/**
+ * Create the credential helper script content (Node.js version)
+ */
+declare function createNodeCredentialHelperScript(contextFilePath: string): string;
+/**
+ * Create a shell-based credential helper script (more portable)
+ */
+declare function createShellCredentialHelperScript(contextFilePath: string): string;
+/**
+ * Configure git to use the credential helper in a workspace
+ */
+declare function configureCredentialHelper(workspacePath: string, context: CredentialHelperContext): Promise<string>;
+/**
+ * Update credentials for an existing workspace
+ * Called when credentials are refreshed
+ */
+declare function updateCredentials(workspacePath: string, newToken: string, newExpiresAt: string): Promise<void>;
+/**
+ * Clean up credential files from a workspace
+ */
+declare function cleanupCredentialFiles(workspacePath: string): Promise<void>;
+/**
+ * Get the git config commands to configure the credential helper
+ */
+declare function getGitCredentialConfig(helperScriptPath: string): string[];
+/**
+ * Output credentials to stdout in Git format
+ */
+declare function outputCredentials(username: string, password: string): void;
+
+export { type AgentPermissions, type AuthPrompt, type AuthPromptEmitter, type AuthResult, type BranchConfig, type BranchInfo, type BranchNamingOptions, type BranchStrategy, type CreateIssueOptions, type CredentialContext, type CredentialGrant, type CredentialGrantStore, type CredentialHelperContext, CredentialService, type CredentialServiceConfig, type CredentialServiceLogger, type CredentialServiceOptions, type CredentialType, DEFAULT_AGENT_PERMISSIONS, DEFAULT_BRANCH_PREFIX, type DeviceCodeResponse, FileTokenStore, type GitCredential, type GitCredentialRequest, type GitHubAppConfig, type GitHubAppInstallation, GitHubPatClient, type GitHubPatClientLogger, type GitHubPatClientOptions, GitHubProvider, type GitHubProviderConfig, type GitHubProviderLogger, type GitProvider, type GitProviderAdapter, type IssueComment, type IssueCommentOptions, type IssueInfo, type IssueState, MemoryTokenStore, OAuthDeviceFlow, type OAuthDeviceFlowConfig, type OAuthDeviceFlowLogger, type OAuthToken, type PermissionLevel, type PullRequestInfo, READONLY_AGENT_PERMISSIONS, type RepositoryScope, type SshCredentials, type TokenCredentials, TokenStore, type TokenStoreOptions, type UserProvidedCredentials, type Workspace, type WorkspaceConfig, type WorkspaceEvent, type WorkspaceEventHandler, type WorkspaceEventType, type WorkspaceFinalization, WorkspaceService, type WorkspaceServiceConfig, type WorkspaceServiceLogger, type WorkspaceServiceOptions, type WorkspaceStatus, cleanupCredentialFiles, configureCredentialHelper, createBranchInfo, createNodeCredentialHelperScript, createShellCredentialHelperScript, filterBranchesByExecution, generateBranchName, generateSlug, getGitCredentialConfig, isManagedBranch, outputCredentials, parseBranchName, updateCredentials };