@sw4rm/js-sdk 0.3.0

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

@@ -0,0 +1,32 @@
+import { ACKLifecycleManager } from './ackLifecycle.js';
+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 EnvelopeLike {
+    message_id: string;
+    message_type: MessageType;
+    correlation_id: string;
+    payload?: Uint8Array;
+}
+type Handler = (env: EnvelopeLike) => Promise<void> | void;
+export declare class MessageProcessor {
+    private handlers;
+    private defaultHandler?;
+    private ack;
+    constructor(ack: ACKLifecycleManager);
+    registerHandler(type: MessageType, handler: Handler): void;
+    setDefaultHandler(handler: Handler): void;
+    process(env: EnvelopeLike): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,6 @@
+export type Duration = {
+    seconds: number | string;
+    nanos?: number;
+};
+export declare function msToDuration(ms: number): Duration;
+export declare function durationToMs(d: Duration | undefined | null): number | undefined;

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

@@ -0,0 +1,15 @@
+export interface WorktreePolicyContext {
+    agent_id: string;
+    current_state: string;
+    target_worktree_id?: string;
+}
+export interface WorktreePolicyHook {
+    canBind(ctx: WorktreePolicyContext, repoId: string, worktreeId: string): boolean;
+    canUnbind(ctx: WorktreePolicyContext): boolean;
+    canSwitch(ctx: WorktreePolicyContext): boolean;
+}
+export declare class DefaultWorktreePolicy implements WorktreePolicyHook {
+    canBind(): boolean;
+    canUnbind(): boolean;
+    canSwitch(): boolean;
+}

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

@@ -0,0 +1,14 @@
+export type WorktreeState = 'UNBOUND' | 'BOUND_HOME' | 'SWITCH_PENDING' | 'BOUND_NON_HOME' | 'BIND_FAILED';
+export declare class PersistentWorktreeState {
+    private state;
+    private repoId?;
+    private worktreeId?;
+    bind(repoId: string, worktreeId: string): void;
+    unbind(): void;
+    setState(state: WorktreeState): void;
+    current(): {
+        state: WorktreeState;
+        repo_id: string | undefined;
+        worktree_id: string | undefined;
+    };
+}

package/dist/types/persistence/persistence.d.ts

@@ -0,0 +1,17 @@
+export interface PersistenceBackend {
+    saveActivity(records: any[]): Promise<void>;
+    loadActivity(): Promise<any[]>;
+    saveAcks(states: any[]): Promise<void>;
+    loadAcks(): Promise<any[]>;
+}
+export declare class JSONFilePersistence implements PersistenceBackend {
+    private baseDir;
+    private activityFile;
+    private acksFile;
+    constructor(baseDir: string);
+    private safeWrite;
+    saveActivity(records: any[]): Promise<void>;
+    loadActivity(): Promise<any[]>;
+    saveAcks(states: any[]): Promise<void>;
+    loadAcks(): Promise<any[]>;
+}

package/dist/types/runtime/ackHelpers.d.ts

@@ -0,0 +1,17 @@
+import type * as grpc from '@grpc/grpc-js';
+import { RouterClient } from '../clients/router.js';
+import { ACKLifecycleManager, AckStage } from '../internal/runtime/ackLifecycle.js';
+import { EnvelopeBuilt } from '../internal/envelope.js';
+export interface SendWithAckOptions {
+    receivedTimeoutMs?: number;
+    correlationIdHeader?: string;
+}
+export type AckExtractor = (env: {
+    msg: EnvelopeBuilt;
+}) => {
+    ackFor?: string;
+    stage?: AckStage;
+} | undefined;
+export declare function sendMessageWithAck(router: RouterClient, inboundStream: grpc.ClientReadableStream<{
+    msg: EnvelopeBuilt;
+}>, envelope: EnvelopeBuilt, ackLifecycle: ACKLifecycleManager, ackExtractor: AckExtractor, opts?: SendWithAckOptions): Promise<void>;

package/dist/types/runtime/activitySync.d.ts

@@ -0,0 +1,9 @@
+import { ActivityBuffer } from '../internal/runtime/activityBuffer.js';
+import { SchedulerClient } from '../clients/scheduler.js';
+export declare class ActivityBufferSync {
+    private buf;
+    private sched;
+    constructor(buf: ActivityBuffer, sched: SchedulerClient);
+    refresh(agentId: string): Promise<void>;
+    purge(agentId: string, taskIds: string[]): Promise<number>;
+}

package/dist/types/runtime/negotiationEvents.d.ts

@@ -0,0 +1,48 @@
+export type NegotiationEventKind = 'open' | 'policy' | 'propose' | 'counter' | 'evaluate' | 'decide' | 'abort' | {
+    unknown: string;
+};
+export interface NegotiationEventBase {
+    kind: string;
+    ts?: string;
+}
+export interface OpenEvent extends NegotiationEventBase {
+    kind: 'open';
+    topic: string;
+    corr: string;
+}
+export interface PolicyEvent extends NegotiationEventBase {
+    kind: 'policy';
+    negotiation_id: string;
+    profile?: string;
+    policy: any;
+}
+export interface PayloadEventBase extends NegotiationEventBase {
+    from: string;
+    ct: string;
+    payload_b64?: string;
+}
+export interface ProposeEvent extends PayloadEventBase {
+    kind: 'propose';
+}
+export interface CounterEvent extends PayloadEventBase {
+    kind: 'counter';
+}
+export interface EvaluateEvent extends NegotiationEventBase {
+    kind: 'evaluate';
+    from: string;
+    score?: number;
+    notes?: string;
+}
+export interface DecideEvent extends NegotiationEventBase {
+    kind: 'decide';
+    by: string;
+    ct: string;
+    result_b64?: string;
+}
+export interface AbortEvent extends NegotiationEventBase {
+    kind: 'abort';
+    reason?: string;
+}
+export type NegotiationEvent = OpenEvent | PolicyEvent | ProposeEvent | CounterEvent | EvaluateEvent | DecideEvent | AbortEvent | NegotiationEventBase;
+export declare function parseNegotiationEvent(json: string): NegotiationEvent;
+export declare function decodeBase64(b64?: string): Uint8Array | undefined;

package/dist/types/runtime/persistenceAdapter.d.ts

@@ -0,0 +1,19 @@
+import { ActivityBuffer } from '../internal/runtime/activityBuffer.js';
+import { ACKLifecycleManager } from '../internal/runtime/ackLifecycle.js';
+import { PersistenceBackend } from '../persistence/persistence.js';
+export interface PersistenceOptions {
+    autosaveMs?: number;
+}
+export declare class RuntimePersistence {
+    private backend;
+    private activity;
+    private acks;
+    private opts?;
+    private timer?;
+    constructor(backend: PersistenceBackend, activity: ActivityBuffer, acks: ACKLifecycleManager, opts?: PersistenceOptions | undefined);
+    static json(baseDir: string, activity: ActivityBuffer, acks: ACKLifecycleManager, opts?: PersistenceOptions): RuntimePersistence;
+    load(): Promise<void>;
+    save(): Promise<void>;
+    startAutosave(): void;
+    stopAutosave(): void;
+}

package/dist/types/runtime/streams.d.ts

@@ -0,0 +1,8 @@
+import { EventEmitter } from 'node:events';
+import { RouterClient } from '../clients/router.js';
+export interface ResilientOptions {
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    multiplier?: number;
+}
+export declare function createResilientIncomingStream(router: RouterClient, agentId: string, opts?: ResilientOptions): EventEmitter;

package/dist/types/secrets/backend.d.ts

@@ -0,0 +1,13 @@
+import type { Scope, SecretKey, SecretValue } from './types.js';
+export interface SecretsBackend {
+    set(scope: Scope, key: SecretKey, value: SecretValue): Promise<void>;
+    get(scope: Scope, key: SecretKey): Promise<string>;
+    list(scope?: Scope | null): Promise<Map<[string | null, string], string>>;
+}
+export declare class Secrets<B extends SecretsBackend> {
+    readonly backend: B;
+    constructor(backend: B);
+    set(scope: Scope, key: SecretKey, value: SecretValue): Promise<void>;
+    get(scope: Scope, key: SecretKey): Promise<string>;
+    list(scope?: Scope | null): Promise<Map<[string | null, string], string>>;
+}

package/dist/types/secrets/backends/file.d.ts

@@ -0,0 +1,12 @@
+import type { SecretsBackend } from '../backend.js';
+import { Scope, SecretKey, SecretValue } from '../types.js';
+export declare class FileBackend implements SecretsBackend {
+    private path;
+    constructor(path?: string);
+    private enforceFilePerms;
+    private safeWrite;
+    private load;
+    set(scope: Scope, key: SecretKey, value: SecretValue): Promise<void>;
+    get(scope: Scope, key: SecretKey): Promise<string>;
+    list(scope?: Scope | null): Promise<Map<[string | null, string], string>>;
+}

package/dist/types/secrets/backends/keyring.d.ts

@@ -0,0 +1,12 @@
+import type { SecretsBackend } from '../backend.js';
+import { Scope, SecretKey, SecretValue } from '../types.js';
+export declare class KeyringBackend implements SecretsBackend {
+    private keytar;
+    private servicePrefix;
+    constructor(servicePrefix?: string);
+    private ensureKeytar;
+    private service;
+    set(scope: Scope, key: SecretKey, value: SecretValue): Promise<void>;
+    get(scope: Scope, key: SecretKey): Promise<string>;
+    list(): Promise<Map<[string | null, string], string>>;
+}

package/dist/types/secrets/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class SecretError extends Error {
+}
+export declare class SecretNotFound extends SecretError {
+    readonly scope: string;
+    readonly key: string;
+    constructor(scope: string, key: string);
+}
+export declare class SecretBackendError extends SecretError {
+}
+export declare class SecretPermissionError extends SecretError {
+}
+export declare class SecretValidationError extends SecretError {
+}

package/dist/types/secrets/factory.d.ts

@@ -0,0 +1,3 @@
+import type { SecretsBackend } from './backend.js';
+export type BackendMode = 'auto' | 'file' | 'keyring';
+export declare function selectBackend(mode?: BackendMode): Promise<[SecretsBackend, string]>;

package/dist/types/secrets/resolver.d.ts

@@ -0,0 +1,11 @@
+import type { SecretsBackend } from './backend.js';
+import { Scope, SecretKey, SecretSource } from './types.js';
+export declare class Resolver<B extends SecretsBackend> {
+    private readonly backend;
+    private readonly env;
+    constructor(backend: B, env?: Record<string, string>);
+    resolve(key: SecretKey, scope: Scope, opts?: {
+        explicit?: string | null;
+        envVar?: string | null;
+    }): Promise<[string, SecretSource]>;
+}

package/dist/types/secrets/types.d.ts

@@ -0,0 +1,21 @@
+export declare enum SecretSource {
+    CLI = "cli",
+    ENV = "env",
+    SCOPED = "scoped",
+    GLOBAL = "global"
+}
+export declare class Scope {
+    readonly name: string | null;
+    constructor(name?: string | null);
+    get isGlobal(): boolean;
+    label(): string;
+}
+export declare class SecretKey {
+    readonly key: string;
+    constructor(key: string);
+}
+export declare class SecretValue {
+    readonly value: string;
+    static MAX_LEN: number;
+    constructor(value: string);
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@sw4rm/js-sdk",
+  "version": "0.3.0",
+  "description": "SW4RM Agentic Protocol JavaScript/TypeScript SDK",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:proto && npm run build:lib",
+    "example": "tsx",
+    "build:proto": "npm run proto:js && npm run proto:ts",
+    "build:lib": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/esm/index.js --external:@grpc/grpc-js --external:keytar",
+    "build:cjs": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --outfile=dist/cjs/index.cjs --external:@grpc/grpc-js --external:keytar",
+    "build:types": "tsc --emitDeclarationOnly --project tsconfig.json --outDir dist/types",
+    "proto:js": "grpc_tools_node_protoc --js_out=import_style=commonjs,binary:src/types/generated --grpc_out=grpc_js:src/types/generated --proto_path=../../protos ../../protos/*.proto",
+    "proto:ts": "grpc_tools_node_protoc --plugin=protoc-gen-ts=./node_modules/.bin/protoc-gen-ts --ts_out=grpc_js:src/types/generated --proto_path=../../protos ../../protos/*.proto",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts,.js",
+    "format": "prettier --write src"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rahulrajaram/sw4rm.git",
+    "directory": "sdks/js_sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/rahulrajaram/sw4rm/issues"
+  },
+  "homepage": "https://github.com/rahulrajaram/sw4rm#readme",
+  "keywords": [
+    "sw4rm",
+    "agent",
+    "protocol",
+    "grpc",
+    "typescript",
+    "javascript"
+  ],
+  "author": "SW4RM Team",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/keytar": "^4.4.0",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "@vitest/coverage-v8": "^1.2.0",
+    "esbuild": "^0.19.0",
+    "eslint": "^8.56.0",
+    "grpc_tools_node_protoc_ts": "^5.3.3",
+    "grpc-tools": "^1.12.4",
+    "prettier": "^3.2.0",
+    "tsx": "^4.15.7",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.10.0",
+    "@grpc/proto-loader": "^0.7.10",
+    "google-protobuf": "^3.21.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}