@sw4rm/js-sdk 0.3.0

package/dist/types/clients/activity.d.ts

@@ -0,0 +1,13 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export declare class ActivityClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    private unary;
+    appendArtifact(artifact: any): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    listArtifacts(negotiation_id: string, kind?: string): Promise<{
+        items: any[];
+    }>;
+}

package/dist/types/clients/connector.d.ts

@@ -0,0 +1,31 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface ToolDescriptor {
+    tool_name: string;
+    input_schema?: string;
+    output_schema?: string;
+    idempotent?: boolean;
+    needs_worktree?: boolean;
+    default_timeout_s?: number;
+    max_concurrency?: number;
+    side_effects?: string;
+}
+export interface ProviderRegisterRequest {
+    provider_id: string;
+    tools: ToolDescriptor[];
+}
+export interface ProviderRegisterResponse {
+    ok: boolean;
+    reason?: string;
+}
+export interface DescribeToolsRequest {
+    provider_id: string;
+}
+export interface DescribeToolsResponse {
+    tools: ToolDescriptor[];
+}
+export declare class ConnectorClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    registerProvider(req: ProviderRegisterRequest): Promise<ProviderRegisterResponse>;
+    describeTools(providerId: string): Promise<ToolDescriptor[]>;
+}

package/dist/types/clients/hitl.d.ts

@@ -0,0 +1,17 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface HitlInvocation {
+    reason_type: string;
+    context: Uint8Array;
+    proposed_actions: string[];
+    priority?: number;
+}
+export interface HitlDecision {
+    action: string;
+    decision_payload?: Uint8Array;
+    rationale?: string;
+}
+export declare class HITLClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    decide(inv: HitlInvocation): Promise<HitlDecision>;
+}

package/dist/types/clients/logging.d.ts

@@ -0,0 +1,18 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface Timestamp {
+    seconds: number | string;
+    nanos?: number;
+}
+export interface LogEvent {
+    ts: Timestamp;
+    correlation_id: string;
+    agent_id: string;
+    event_type: string;
+    level: string;
+    details_json: string;
+}
+export declare class LoggingClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    ingest(evt: LogEvent): Promise<boolean>;
+}

package/dist/types/clients/negotiation.d.ts

@@ -0,0 +1,53 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface Empty {
+}
+export interface NegotiationOpen {
+    negotiation_id: string;
+    correlation_id: string;
+    topic: string;
+    participants: string[];
+    intensity: string;
+    debate_timeout?: {
+        seconds: number | string;
+        nanos?: number;
+    };
+}
+export interface Proposal {
+    negotiation_id: string;
+    from_agent: string;
+    content_type: string;
+    payload: Uint8Array;
+}
+export interface CounterProposal {
+    negotiation_id: string;
+    from_agent: string;
+    content_type: string;
+    payload: Uint8Array;
+}
+export interface Evaluation {
+    negotiation_id: string;
+    from_agent: string;
+    confidence_score?: number;
+    notes?: string;
+}
+export interface Decision {
+    negotiation_id: string;
+    decided_by: string;
+    content_type: string;
+    result: Uint8Array;
+}
+export interface AbortRequest {
+    negotiation_id: string;
+    reason?: string;
+}
+export declare class NegotiationClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    private unary;
+    open(req: NegotiationOpen): Promise<Empty>;
+    propose(req: Proposal): Promise<Empty>;
+    counter(req: CounterProposal): Promise<Empty>;
+    evaluate(req: Evaluation): Promise<Empty>;
+    decide(req: Decision): Promise<Empty>;
+    abort(req: AbortRequest): Promise<Empty>;
+}

package/dist/types/clients/reasoning.d.ts

@@ -0,0 +1,13 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export declare class ReasoningClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    checkParallelism(scopeA: string, scopeB: string): Promise<{
+        confidence_score: number;
+        notes?: string;
+    }>;
+    evaluateDebate(negotiationId: string, proposalA: string, proposalB: string, intensity?: string): Promise<{
+        confidence_score: number;
+        notes?: string;
+    }>;
+}

package/dist/types/clients/registry.d.ts

@@ -0,0 +1,21 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface AgentDescriptor {
+    agent_id: string;
+    name: string;
+    description: string;
+    capabilities: string[];
+    communication_class: string;
+    modalities_supported: string[];
+    reasoning_connectors: string[];
+    public_key?: Uint8Array;
+}
+export declare class RegistryClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    registerAgent(agent: AgentDescriptor): Promise<{
+        accepted: boolean;
+        reason?: string;
+    }>;
+    heartbeat(agentId: string, state: string, health?: Record<string, string>): Promise<boolean>;
+    deregisterAgent(agentId: string, reason?: string): Promise<boolean>;
+}

package/dist/types/clients/router.d.ts

@@ -0,0 +1,15 @@
+import * as grpc from '@grpc/grpc-js';
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+import { EnvelopeBuilt } from '../internal/envelope.js';
+export interface SendResult {
+    accepted: boolean;
+    reason?: string;
+}
+export declare class RouterClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    sendMessage(envelope: EnvelopeBuilt): Promise<SendResult>;
+    streamIncoming(agentId: string, meta?: grpc.Metadata): grpc.ClientReadableStream<{
+        msg: EnvelopeBuilt;
+    }>;
+}

package/dist/types/clients/scheduler.d.ts

@@ -0,0 +1,61 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface SubmitTaskRequest {
+    agent_id: string;
+    task_id: string;
+    priority: number;
+    params: Uint8Array;
+    content_type: string;
+    scope: string;
+}
+export interface SubmitTaskResponse {
+    accepted: boolean;
+    reason?: string;
+}
+export interface PreemptRequest {
+    agent_id: string;
+    task_id: string;
+    reason?: string;
+}
+export interface PreemptResponse {
+    enqueued: boolean;
+}
+export interface ShutdownAgentRequest {
+    agent_id: string;
+    grace_period?: {
+        seconds: number | string;
+        nanos?: number;
+    };
+}
+export interface ShutdownAgentResponse {
+    ok: boolean;
+}
+export interface PollActivityBufferRequest {
+    agent_id: string;
+}
+export interface ActivityEntry {
+    task_id: string;
+    repo_id: string;
+    worktree_id: string;
+    branch: string;
+    description: string;
+    timestamp: string;
+}
+export interface PollActivityBufferResponse {
+    entries: ActivityEntry[];
+}
+export interface PurgeActivityRequest {
+    agent_id: string;
+    task_ids: string[];
+}
+export interface PurgeActivityResponse {
+    purged: number;
+}
+export declare class SchedulerClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    submitTask(req: SubmitTaskRequest): Promise<SubmitTaskResponse>;
+    requestPreemption(agentId: string, taskId: string, reason?: string): Promise<PreemptResponse>;
+    shutdownAgent(agentId: string, graceMs: number): Promise<ShutdownAgentResponse>;
+    pollActivityBuffer(agentId: string): Promise<ActivityEntry[]>;
+    purgeActivity(agentId: string, taskIds: string[]): Promise<number>;
+}

package/dist/types/clients/schedulerPolicy.d.ts

@@ -0,0 +1,31 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export declare class SchedulerPolicyClient extends BaseClient {
+    private client;
+    constructor(opts: ClientOptions);
+    private unary;
+    setWagglePolicy(policy: any): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    getWagglePolicy(): Promise<{
+        policy?: any;
+    }>;
+    setPolicyProfiles(profiles: any[]): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    listPolicyProfiles(): Promise<{
+        profiles: any[];
+    }>;
+    getEffectivePolicy(negotiation_id: string): Promise<{
+        effective?: any;
+    }>;
+    submitEvaluation(negotiation_id: string, report: any): Promise<{
+        accepted: boolean;
+        reason?: string;
+    }>;
+    hitlAction(negotiation_id: string, action: string, rationale?: string): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}

package/dist/types/clients/tool.d.ts

@@ -0,0 +1,50 @@
+import * as grpc from '@grpc/grpc-js';
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+export interface ExecutionPolicy {
+    timeout?: {
+        seconds: number | string;
+        nanos?: number;
+    };
+    max_retries?: number;
+    backoff?: string;
+    worktree_required?: boolean;
+    network_policy?: string;
+    privilege_level?: string;
+    budget_cpu_ms?: string | number;
+    budget_wall_ms?: string | number;
+}
+export interface ToolCall {
+    call_id: string;
+    tool_name: string;
+    provider_id?: string;
+    content_type: string;
+    args: Uint8Array;
+    policy?: ExecutionPolicy;
+    stream?: boolean;
+}
+export interface ToolFrame {
+    call_id: string;
+    frame_no: string | number;
+    final: boolean;
+    content_type: string;
+    data: Uint8Array;
+    summary?: Uint8Array;
+}
+export interface ToolError {
+    call_id: string;
+    error_code?: string;
+    message?: string;
+}
+export declare class ToolClient extends BaseClient {
+    private client;
+    private getWorktreeState?;
+    constructor(opts: ClientOptions, deps?: {
+        getWorktreeState?: () => {
+            state: string;
+        };
+    });
+    private ensureWorktreeIfNeeded;
+    call(call: ToolCall): Promise<ToolFrame>;
+    callStream(call: ToolCall, meta?: grpc.Metadata): grpc.ClientReadableStream<ToolFrame>;
+    cancel(call: ToolCall): Promise<ToolError>;
+}

package/dist/types/clients/worktree.d.ts

@@ -0,0 +1,25 @@
+import { BaseClient, ClientOptions } from '../internal/baseClient.js';
+import { WorktreePolicyHook } from '../internal/worktreePolicy.js';
+export declare class WorktreeClient extends BaseClient {
+    private client;
+    private policy;
+    constructor(opts: ClientOptions);
+    setPolicy(policy: WorktreePolicyHook): void;
+    bind(agentId: string, repoId: string, worktreeId: string): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    unbind(agentId: string): Promise<boolean>;
+    requestSwitch(agentId: string, targetWorktreeId: string, requiresHitl: boolean): Promise<{
+        state: string;
+        repo_id?: string;
+        worktree_id?: string;
+    }>;
+    approveSwitch(agentId: string, targetWorktreeId: string, ttlMs: number): Promise<string>;
+    rejectSwitch(agentId: string, reason?: string): Promise<string>;
+    status(agentId: string): Promise<{
+        state: string;
+        repo_id?: string;
+        worktree_id?: string;
+    }>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,41 @@
+export declare const version = "0.3.0";
+export * from './clients/router.js';
+export * from './clients/scheduler.js';
+export * from './clients/schedulerPolicy.js';
+export * from './clients/worktree.js';
+export * from './clients/tool.js';
+export { LoggingClient, type LogEvent, } from './clients/logging.js';
+export * from './clients/activity.js';
+export * from './clients/hitl.js';
+export * from './clients/negotiation.js';
+export * from './clients/reasoning.js';
+export * from './clients/connector.js';
+export * from './clients/registry.js';
+export { buildEnvelope, type EnvelopeBuilt, type EnvelopeInput, nowTimestamp, type Timestamp, } from './internal/envelope.js';
+export * from './internal/errorMapping.js';
+export * from './internal/baseClient.js';
+export * from './internal/time.js';
+export * from './internal/interceptors.js';
+export * from './internal/worktreeState.js';
+export * from './internal/worktreePolicy.js';
+export * from './internal/runtime/activityBuffer.js';
+export * from './internal/runtime/ackLifecycle.js';
+export * from './internal/runtime/messageProcessor.js';
+export * from './runtime/ackHelpers.js';
+export * from './runtime/activitySync.js';
+export * from './runtime/streams.js';
+export * from './runtime/negotiationEvents.js';
+export * from './persistence/persistence.js';
+export * from './internal/ids.js';
+export * from './internal/idempotency.js';
+export * from './runtime/persistenceAdapter.js';
+export * from './internal/errorMapper.js';
+export * from './internal/ack.js';
+export * from './internal/control.js';
+export * from './secrets/types.js';
+export * from './secrets/errors.js';
+export * from './secrets/backend.js';
+export * from './secrets/resolver.js';
+export * from './secrets/backends/file.js';
+export * from './secrets/backends/keyring.js';
+export * from './secrets/factory.js';

package/dist/types/internal/ack.d.ts

@@ -0,0 +1,13 @@
+import { EnvelopeBuilt } from './envelope.js';
+export interface AckPayload {
+    ack_for_message_id: string;
+    ack_stage: number;
+    error_code?: number;
+    note?: string;
+}
+export declare function buildAckEnvelope(params: {
+    producer_id: string;
+    correlation_id?: string;
+    ack: AckPayload;
+    content_type?: 'application/json';
+}): EnvelopeBuilt;

package/dist/types/internal/baseClient.d.ts

@@ -0,0 +1,33 @@
+import * as grpc from '@grpc/grpc-js';
+import { ErrorCodeMapper } from './errorMapper.js';
+import { InterceptorChain } from './interceptors.js';
+export interface RetryPolicy {
+    maxAttempts: number;
+    initialBackoffMs: number;
+    maxBackoffMs: number;
+    multiplier: number;
+}
+export interface ClientOptions {
+    address: string;
+    deadlineMs?: number;
+    retry?: RetryPolicy;
+    userAgent?: string;
+    interceptors?: (chain: InterceptorChain) => void;
+    errorMapper?: (m: ErrorCodeMapper) => void;
+}
+export declare class BaseClient {
+    protected readonly address: string;
+    protected readonly deadlineMs: number;
+    protected readonly retry: RetryPolicy;
+    protected readonly userAgent: string;
+    private readonly pkgDef;
+    private readonly root;
+    protected readonly interceptors: InterceptorChain;
+    protected readonly errorMapper: ErrorCodeMapper;
+    constructor(opts: ClientOptions);
+    protected channelCredentials(): grpc.ChannelCredentials;
+    protected metadata(base?: grpc.Metadata): grpc.Metadata;
+    protected deadlineFromNow(): Date;
+    protected getServiceClient<T = any>(fqn: string): T;
+    protected withRetryUnary<Req, Res>(fn: () => Promise<Res>, methodName?: string, mdForCtx?: grpc.Metadata): Promise<Res>;
+}

package/dist/types/internal/control.d.ts

@@ -0,0 +1,22 @@
+export declare const CT_SCHEDULER_COMMAND_V1 = "application/vnd.sw4rm.scheduler.command+json;v=1";
+export declare const CT_AGENT_REPORT_V1 = "application/vnd.sw4rm.agent.report+json;v=1";
+export type SchedulerStage = 'prompt' | 'plan' | 'run';
+export interface SchedulerCommandV1 {
+    stage: SchedulerStage;
+    input?: unknown;
+}
+export interface AgentReportFileV1 {
+    path: string;
+    b64: string;
+}
+export interface AgentReportV1 {
+    agent_id?: string;
+    stage?: string;
+    success?: boolean;
+    files?: AgentReportFileV1[];
+    logs?: string[];
+    error?: string;
+}
+export declare function encodeSchedulerCommandV1(cmd: SchedulerCommandV1): Uint8Array;
+export declare function decodeAgentReportV1(payload: Uint8Array): AgentReportV1;
+export declare function normalizeReportPaths(report: AgentReportV1): AgentReportV1;

package/dist/types/internal/envelope.d.ts

@@ -0,0 +1,53 @@
+export type Timestamp = {
+    seconds: number;
+    nanos: number;
+};
+export declare enum MessageType {
+    MESSAGE_TYPE_UNSPECIFIED = 0,
+    CONTROL = 1,
+    DATA = 2,
+    HEARTBEAT = 3,
+    NOTIFICATION = 4,
+    ACKNOWLEDGEMENT = 5,
+    HITL_INVOCATION = 6,
+    WORKTREE_CONTROL = 7,
+    NEGOTIATION = 8,
+    TOOL_CALL = 9,
+    TOOL_RESULT = 10,
+    TOOL_ERROR = 11
+}
+export interface EnvelopeInput {
+    producer_id: string;
+    message_type: MessageType;
+    payload?: Uint8Array | Buffer;
+    content_type?: string;
+    correlation_id?: string;
+    idempotency_token?: string;
+    sequence_number?: number;
+    retry_count?: number;
+    repo_id?: string;
+    worktree_id?: string;
+    hlc_timestamp?: string;
+    ttl_ms?: number;
+    timestamp?: Date;
+}
+export interface EnvelopeBuilt {
+    message_id: string;
+    idempotency_token?: string;
+    producer_id: string;
+    correlation_id: string;
+    sequence_number: number;
+    retry_count: number;
+    message_type: MessageType;
+    content_type: string;
+    content_length?: number;
+    repo_id?: string;
+    worktree_id?: string;
+    hlc_timestamp: string;
+    ttl_ms?: number;
+    timestamp: Timestamp;
+    payload?: Uint8Array;
+}
+export declare function nowTimestamp(date?: Date): Timestamp;
+export declare function nowHlcStub(date?: Date): string;
+export declare function buildEnvelope(input: EnvelopeInput): EnvelopeBuilt;

package/dist/types/internal/errorMapper.d.ts

@@ -0,0 +1,13 @@
+import { ErrorCode } from './errorMapping.js';
+export type GrpcErrorInfo = {
+    status?: number;
+    message?: string;
+    details?: string;
+};
+export type ErrorMapRule = (err: GrpcErrorInfo) => ErrorCode | undefined;
+export declare class ErrorCodeMapper {
+    private rules;
+    constructor(rules?: ErrorMapRule[]);
+    addRule(rule: ErrorMapRule): void;
+    map(err: GrpcErrorInfo, fallback: (status?: number) => ErrorCode): ErrorCode;
+}

package/dist/types/internal/errorMapping.d.ts

@@ -0,0 +1,27 @@
+export declare enum ErrorCode {
+    ERROR_CODE_UNSPECIFIED = 0,
+    BUFFER_FULL = 1,
+    NO_ROUTE = 2,
+    ACK_TIMEOUT = 3,
+    AGENT_UNAVAILABLE = 4,
+    AGENT_SHUTDOWN = 5,
+    VALIDATION_ERROR = 6,
+    PERMISSION_DENIED = 7,
+    UNSUPPORTED_MESSAGE_TYPE = 8,
+    OVERSIZE_PAYLOAD = 9,
+    TOOL_TIMEOUT = 10,
+    PARTIAL_DELIVERY = 11,
+    FORCED_PREEMPTION = 12,
+    TTL_EXPIRED = 13,
+    INTERNAL_ERROR = 99
+}
+export declare class Sw4rmError extends Error {
+    readonly code: ErrorCode;
+    readonly grpcStatus?: number;
+    readonly details?: string;
+    constructor(message: string, code: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+export declare function mapGrpcStatusToErrorCode(status: number): ErrorCode;

package/dist/types/internal/idempotency.d.ts

@@ -0,0 +1,6 @@
+export interface IdempotencyInput {
+    producer_id: string;
+    operation: string;
+    canonical_bytes: Uint8Array | Buffer;
+}
+export declare function computeIdempotencyToken(input: IdempotencyInput): string;

package/dist/types/internal/ids.d.ts

@@ -0,0 +1 @@
+export declare function uuidv4(): string;

package/dist/types/internal/interceptors.d.ts

@@ -0,0 +1,25 @@
+export interface UnaryContext {
+    method: string;
+    metadata: Map<string, string>;
+    startTime: number;
+}
+export interface UnaryInterceptor {
+    onRequest?(ctx: UnaryContext): void;
+    onResponse?(ctx: UnaryContext, status: {
+        ok: boolean;
+        error?: unknown;
+        durationMs: number;
+    }): void;
+}
+export declare class InterceptorChain {
+    private chain;
+    use(i: UnaryInterceptor): void;
+    runRequest(ctx: UnaryContext): void;
+    runResponse(ctx: UnaryContext, status: {
+        ok: boolean;
+        error?: unknown;
+        durationMs: number;
+    }): void;
+}
+export declare function timingInterceptor(): UnaryInterceptor;
+export declare function loggingInterceptor(): UnaryInterceptor;

package/dist/types/internal/runtime/ackLifecycle.d.ts

@@ -0,0 +1,25 @@
+export declare enum AckStage {
+    ACK_STAGE_UNSPECIFIED = 0,
+    RECEIVED = 1,
+    READ = 2,
+    FULFILLED = 3,
+    REJECTED = 4,
+    FAILED = 5,
+    TIMED_OUT = 6
+}
+export interface AckState {
+    messageId: string;
+    stage: AckStage;
+    lastUpdateIso: string;
+    note?: string;
+    errorCode?: number;
+}
+export declare class ACKLifecycleManager {
+    private acks;
+    mark(messageId: string, stage: AckStage, note?: string, errorCode?: number): void;
+    get(messageId: string): AckState | undefined;
+    recent(limit?: number): AckState[];
+    reconcileLateAck(messageId: string, stage: AckStage): void;
+    toJSON(): AckState[];
+    fromJSON(states: AckState[]): void;
+}

package/dist/types/internal/runtime/activityBuffer.d.ts

@@ -0,0 +1,31 @@
+export interface ActivityRecord {
+    task_id: string;
+    repo_id: string;
+    worktree_id: string;
+    branch: string;
+    description: string;
+    timestamp: string;
+}
+export interface BufferStrategy {
+    prune(records: ActivityRecord[], maxEntries: number): ActivityRecord[];
+}
+export declare class MaxEntriesStrategy implements BufferStrategy {
+    prune(records: ActivityRecord[], maxEntries: number): ActivityRecord[];
+}
+export declare class ActivityBuffer {
+    private records;
+    private maxEntries;
+    private strategy;
+    constructor(opts?: {
+        maxEntries?: number;
+        strategy?: BufferStrategy;
+    });
+    upsert(rec: ActivityRecord): void;
+    remove(taskId: string): void;
+    list(): ActivityRecord[];
+    recent(limit?: number): ActivityRecord[];
+    reconcile(knownTaskIds: Set<string>): void;
+    private prune;
+    toJSON(): ActivityRecord[];
+    fromJSON(records: ActivityRecord[]): void;
+}