branchora-sdk 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "branchora-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Branchora JavaScript and TypeScript SDK",
   "license": "Apache-2.0",
   "type": "module",

package/types/core/agent-identity.d.ts

@@ -0,0 +1,12 @@
+export declare const AGENT_CAPABILITIES: readonly ["git:read", "git:write", "git:review", "git:merge", "git:check", "execution:read", "execution:write"];
+export type AgentCapability = (typeof AGENT_CAPABILITIES)[number];
+export interface AgentIdentity {
+    agentId: string;
+    credentialId: string;
+    projectId: string;
+    capabilities: AgentCapability[];
+    writeBranches: string[];
+    generation: number;
+}
+/** Only a trailing wildcard is supported; no regular expressions are accepted from callers. */
+export declare function matchesAgentBranch(branch: string, patterns: readonly string[]): boolean;

package/types/sdk/client.d.ts

@@ -1,4 +1,6 @@
 import type { ContextBlock, Provider, TraceEvent } from '../core/types.js';
+import { type AgentIdentity } from '../core/agent-identity.js';
+import type { AgentAccessOptions, AgentAccessRecord, AgentCredentialRecord, AgentSession, ClientIdentity, CommitCheckOptions, CommitFilesOptions, GitCommitResult, GitTransport, IssuedAgentCredential, PullRequestDetail, PullRequestOptions, PullRequestRecord, RepositoryAutomation, RepositoryFile, RepositoryRefs, ReviewOptions } from './types.js';
 export declare class TraceGitError extends Error {
     code: string;
     status: number;
@@ -32,6 +34,7 @@ export interface RunOptions {
     recordType?: 'connected' | 'validation';
     externalSessionId?: string;
 }
+export type AgentRunOptions = Omit<RunOptions, 'projectId' | 'rootAgentId'>;
 export interface GenerateOptions {
     provider: Provider;
     model: string;
@@ -64,7 +67,16 @@ export declare class TraceGitClient {
     readonly url: string;
     private readonly apiKey;
     private readonly transport;
+    private authenticatedAgent?;
+    private pendingIdentity?;
     constructor(options: ClientOptions);
+    get isAgentCredential(): boolean;
+    private rememberIdentity;
+    /** Resolves machine authority once; every Worker operation still rechecks live authority. */
+    assignedAgent(): Promise<AgentIdentity | undefined>;
+    assertExecutionAgent(agentId: string): Promise<void>;
+    private assertAdministration;
+    private authorizeProject;
     raw(path: string, init?: RequestInit): Promise<Response>;
     request<T>(path: string, method?: string, body?: unknown, idempotent?: boolean): Promise<T>;
     createAgent(options: AgentOptions): Promise<{
@@ -72,26 +84,51 @@ export declare class TraceGitClient {
         version: number;
     }>;
     createRun(options: RunOptions): Promise<TraceExecution>;
+    createAgentRun(options: AgentRunOptions): Promise<TraceExecution>;
     execution(runId: string, agentId: string): TraceExecution;
     events(events: TraceEvent[]): Promise<{
         inserted: number;
         duplicates: number;
     }>;
-    me(): Promise<{
-        principal: {
-            workspaceId: string;
-            role: string;
-        };
-        workspace: {
-            id: string;
-            name: string;
-        };
+    me(): Promise<ClientIdentity>;
+    agentIdentity(): Promise<AgentSession>;
+    repositoryAutomation(projectId: string): Promise<RepositoryAutomation>;
+    configureAgentRepository(projectId: string, expectedVersion?: number): Promise<{
+        mode: "agents-only";
+        version: number;
+    }>;
+    listAgentAccess(projectId: string): Promise<AgentAccessRecord[]>;
+    grantAgentAccess(projectId: string, agentId: string, options: AgentAccessOptions): Promise<{
+        agentId: string;
+        projectId: string;
+        generation: number;
+    }>;
+    issueAgentCredential(projectId: string, agentId: string, name: string, expiresInHours?: number): Promise<IssuedAgentCredential>;
+    listAgentCredentials(projectId: string): Promise<AgentCredentialRecord[]>;
+    revokeAgentAccess(projectId: string, agentId: string): Promise<{
+        revoked: true;
+    }>;
+    revokeAgentCredential(projectId: string, credentialId: string): Promise<{
+        revoked: true;
     }>;
     providerHeaders(runId: string, agentId: string, requestId?: string): Record<string, string>;
-    gitTransport(projectId: string): {
-        remote: string;
-        headers: Record<string, string>;
-    };
+    gitTransport(projectId: string): GitTransport;
+    repositoryRefs(projectId: string): Promise<RepositoryRefs>;
+    readRepositoryFile(projectId: string, path: string, ref?: string): Promise<RepositoryFile>;
+    compareRepository(projectId: string, base: string, head: string): Promise<Record<string, unknown>>;
+    createBranch(projectId: string, branch: string, from: string, operationId?: string): Promise<GitCommitResult>;
+    commitFiles(projectId: string, options: CommitFilesOptions): Promise<GitCommitResult>;
+    listPullRequests(projectId: string): Promise<PullRequestRecord[]>;
+    pullRequest(projectId: string, pullId: string): Promise<PullRequestDetail>;
+    openPullRequest(projectId: string, options: PullRequestOptions): Promise<PullRequestRecord>;
+    reviewPullRequest(projectId: string, pullId: string, options: ReviewOptions): Promise<{
+        id: string;
+    }>;
+    recordCommitCheck(projectId: string, options: CommitCheckOptions): Promise<{
+        recorded: true;
+    }>;
+    mergePullRequest(projectId: string, pullId: string, expectedVersion: number, operationId?: string): Promise<GitCommitResult>;
+    publishRun(runId: string): Promise<Record<string, unknown>>;
     createWallet(options: {
         id?: string;
         commandId?: string;

package/types/sdk/index.d.ts

@@ -1,6 +1,9 @@
 export { TraceGitClient, TraceExecution, TraceGitError } from './client.js';
 export { TraceGitClient as BranchoraClient, TraceExecution as BranchoraExecution, TraceGitError as BranchoraError, } from './client.js';
-export type { ClientOptions, AgentOptions, RunOptions, GenerateOptions, DecisionOptions, } from './client.js';
+export type { ClientOptions, AgentOptions, RunOptions, AgentRunOptions, GenerateOptions, DecisionOptions, } from './client.js';
+export type { AgentAccessOptions, AgentAccessRecord, AgentCredentialRecord, AgentPrincipal, AgentSession, ClientIdentity, ClientPrincipal, CommitCheckOptions, CommitFilesOptions, GitCommitResult, GitFileChange, GitTransport, IssuedAgentCredential, PullRequestDetail, PullRequestOptions, PullRequestRecord, RepositoryAutomation, RepositoryFile, RepositoryRefs, ReviewOptions, } from './types.js';
+export { AGENT_CAPABILITIES, matchesAgentBranch } from '../core/agent-identity.js';
+export type { AgentCapability, AgentIdentity } from '../core/agent-identity.js';
 export { buildSharedContext, estimatedTextTokens } from '../core/context.js';
 export { calculateCost, usdToNanos, nanosToUsd } from '../core/money.js';
 export { normalizeUsage } from '../core/usage.js';

package/types/sdk/types.d.ts

@@ -0,0 +1,155 @@
+import type { AgentCapability, AgentIdentity } from '../core/agent-identity.js';
+export interface ClientPrincipal {
+    id?: string;
+    workspaceId: string;
+    role: string;
+    name?: string;
+    source?: 'api-key' | 'session' | 'access' | 'agent';
+    agent?: AgentIdentity;
+}
+export interface AgentPrincipal extends ClientPrincipal {
+    id: string;
+    role: 'operator';
+    source: 'agent';
+    agent: AgentIdentity;
+}
+export interface ClientIdentity {
+    principal: ClientPrincipal;
+    workspace: {
+        id: string;
+        name: string;
+    };
+}
+export interface AgentSession {
+    principal: AgentPrincipal;
+    protocol: 'branchora.agents.v1';
+    gitRemote: string;
+    headless: true;
+}
+export interface RepositoryAutomation {
+    mode: 'legacy' | 'agents-only';
+    version: number;
+    configured_at?: string;
+}
+export interface AgentAccessOptions {
+    capabilities: AgentCapability[];
+    writeBranches: string[];
+    expectedGeneration?: number;
+}
+/** Administration lists retain the server's field names and never include credential tokens. */
+export interface AgentAccessRecord {
+    agent_id: string;
+    name: string;
+    capabilities_json: string;
+    write_branches_json: string;
+    generation: number;
+    revoked_at: string | null;
+    configured_at: string;
+}
+export interface AgentCredentialRecord {
+    id: string;
+    agent_id: string;
+    project_id: string;
+    prefix: string;
+    name: string;
+    created_at: string;
+    expires_at: string;
+    revoked_at: string | null;
+}
+export interface IssuedAgentCredential {
+    id: string;
+    token: string;
+    expiresAt: string;
+    agentId: string;
+    projectId: string;
+}
+export interface GitTransport {
+    remote: string;
+    headers: Record<string, string>;
+}
+export interface RepositoryRefs {
+    branches: Array<{
+        name: string;
+        sha: string | null;
+        ref?: string;
+    }>;
+    tags: Array<{
+        name: string;
+        sha: string;
+        ref?: string;
+    }>;
+    defaultBranch: string;
+}
+export interface RepositoryFile {
+    path: string;
+    content: string | null;
+    binary: boolean;
+    bytes: number;
+    contentType: string;
+}
+export interface GitFileChange {
+    path: string;
+    /** null deletes the file. Empty content writes an empty file. */
+    content: string | null;
+    mode?: '100644' | '100755';
+}
+export interface CommitFilesOptions {
+    operationId?: string;
+    branch: string;
+    expectedHead: string | null;
+    message: string;
+    files: GitFileChange[];
+    runId?: string;
+}
+export interface GitCommitResult {
+    sha: string;
+    branch?: string;
+    treeHash?: string;
+    created?: boolean;
+    method?: 'fast-forward' | 'merge-commit';
+    duplicate?: boolean;
+}
+export interface PullRequestOptions {
+    title: string;
+    description?: string;
+    sourceBranch: string;
+    targetBranch: string;
+    draft?: boolean;
+}
+export interface PullRequestRecord {
+    id: string;
+    project_id: string;
+    number: number;
+    title: string;
+    description: string;
+    source_branch: string;
+    target_branch: string;
+    base_sha: string;
+    head_sha: string;
+    merge_sha?: string | null;
+    target_sha?: string;
+    status: 'open' | 'closed' | 'merged';
+    draft: number;
+    author_id: string;
+    author_name: string;
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface PullRequestDetail {
+    pull: PullRequestRecord;
+    reviews: Record<string, unknown>[];
+    comments: Record<string, unknown>[];
+    readiness: Record<string, unknown>;
+}
+export interface ReviewOptions {
+    state: 'approved' | 'changes_requested' | 'commented';
+    headSha: string;
+    body?: string;
+}
+export interface CommitCheckOptions {
+    commitSha: string;
+    name: string;
+    status: 'pending' | 'passed' | 'failed';
+    details?: Record<string, unknown>;
+}