@cofy-x/axern-sdk 0.3.1 → 0.4.0

package/dist/client/index.d.ts

@@ -40,11 +40,16 @@ export interface CreateServiceOptions {
     limitMemory?: ResourceQuantity;
     labels?: Record<string, string>;
 }
+export interface ReadRunOutputOptions {
+    cursor?: string;
+    follow?: boolean;
+}
 export declare class AxernClient {
     readonly endpoint: string;
     private readonly credentials;
     private readonly controlOptions;
     private readonly environmentControl;
+    private readonly runControl;
     private readonly serviceControl;
     private readonly tunnelControl;
     private readonly gatewayTransport;
@@ -54,6 +59,8 @@ export declare class AxernClient {
     close(): void;
     createEnvironment(options: CreateEnvironmentOptions): Promise<Record<string, unknown>>;
     deleteEnvironment(environmentId: string): Promise<void>;
+    watchRun(runId: string, afterVersion?: number): AsyncGenerator<Record<string, unknown>>;
+    readRunOutput(runId: string, options?: ReadRunOutputOptions): AsyncGenerator<Record<string, unknown>>;
     createService(options: CreateServiceOptions): Promise<Record<string, unknown>>;
     deleteService(serviceId: string): Promise<void>;
     listServiceReplicas(serviceId: string): Promise<Record<string, unknown>[]>;

package/dist/client/index.js

@@ -17,6 +17,7 @@ export class AxernClient {
     credentials;
     controlOptions;
     environmentControl;
+    runControl;
     serviceControl;
     tunnelControl;
     gatewayTransport;
@@ -55,9 +56,11 @@ export class AxernClient {
             "v1",
             "EnvironmentControl",
         ]);
+        const RunControl = serviceConstructor(["axern", "control", "run", "v1", "RunControl"]);
         const ServiceControl = serviceConstructor(["axern", "control", "service", "v1", "ServiceControl"]);
         const TunnelControl = serviceConstructor(["axern", "control", "tunnel", "v1", "TunnelControl"]);
         this.environmentControl = new EnvironmentControl(this.endpoint, this.credentials, this.controlOptions);
+        this.runControl = new RunControl(this.endpoint, this.credentials, this.controlOptions);
         this.serviceControl = new ServiceControl(this.endpoint, this.credentials, this.controlOptions);
         this.tunnelControl = new TunnelControl(this.endpoint, this.credentials, this.controlOptions);
     }
@@ -78,6 +81,7 @@ export class AxernClient {
     }
     close() {
         this.environmentControl.close();
+        this.runControl.close();
         this.serviceControl.close();
         this.tunnelControl.close();
     }
@@ -114,6 +118,83 @@ export class AxernClient {
             throw mapRpcError(error, "delete environment");
         }
     }
+    async *watchRun(runId, afterVersion = 0) {
+        if (afterVersion < 0) {
+            throw new Error("afterVersion must be non-negative");
+        }
+        let version = afterVersion;
+        let retryDelayMs = 100;
+        for (;;) {
+            const stream = serverStream(this.runControl, "WatchRun", {
+                run_id: required("runId", runId),
+                after_version: version,
+            });
+            try {
+                for await (const response of stream) {
+                    const run = response.run;
+                    if (run === undefined)
+                        continue;
+                    const nextVersion = Number(run.version ?? 0);
+                    if (nextVersion <= version)
+                        continue;
+                    version = nextVersion;
+                    retryDelayMs = 100;
+                    yield run;
+                }
+                return;
+            }
+            catch (error) {
+                if (!transientReadError(error))
+                    throw mapRpcError(error, "watch run");
+            }
+            await sleep(retryDelayMs);
+            retryDelayMs = Math.min(retryDelayMs * 2, 2_000);
+        }
+    }
+    async *readRunOutput(runId, options = {}) {
+        const response = await unary(this.runControl, "GetRun", { run_id: required("runId", runId) });
+        const allocationId = String(response.run?.allocation_id ?? "");
+        if (allocationId === "")
+            throw new Error(`run ${runId} output is not available yet`);
+        let cursor = options.cursor ?? "";
+        let retryDelayMs = 100;
+        let notFoundSince = 0;
+        for (;;) {
+            const NodeSandbox = serviceConstructor(["axern", "node", "sandbox", "v1", "NodeSandbox"]);
+            const node = new NodeSandbox(this.endpoint, this.credentials, this.controlOptions);
+            const stream = serverStream(node, "ReadOutput", {
+                allocation_id: allocationId,
+                cursor,
+                follow: options.follow ?? false,
+            });
+            try {
+                for await (const event of stream) {
+                    cursor = String(event.next_cursor ?? cursor);
+                    retryDelayMs = 100;
+                    notFoundSince = 0;
+                    yield event;
+                }
+                return;
+            }
+            catch (error) {
+                const code = error.code;
+                const startupNotFound = code === grpc.status.NOT_FOUND;
+                if (!(options.follow ?? false) || (!transientReadError(error) && !startupNotFound)) {
+                    throw mapRpcError(error, "read run output");
+                }
+                if (startupNotFound) {
+                    notFoundSince ||= Date.now();
+                    if (Date.now() - notFoundSince >= 30_000)
+                        throw mapRpcError(error, "read run output");
+                }
+            }
+            finally {
+                node.close();
+            }
+            await sleep(retryDelayMs);
+            retryDelayMs = Math.min(retryDelayMs * 2, 2_000);
+        }
+    }
     async createService(options) {
         const resources = buildResourceSpec(options);
         try {
@@ -180,6 +261,17 @@ function serviceVolumeMounts(mounts) {
         options: [...(mount.options ?? [])],
     }));
 }
+function serverStream(client, method, request) {
+    const fn = client[method];
+    return fn.call(client, request);
+}
+function transientReadError(error) {
+    const code = error.code;
+    return code === grpc.status.UNAVAILABLE || code === grpc.status.DEADLINE_EXCEEDED;
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
 function controlCredentials(options) {
     const configured = [options.tlsCaCert, options.tlsCert, options.tlsKey].filter((value) => value !== undefined && value !== "");
     if (configured.length === 0) {

package/dist/generated/proto.js

@@ -15,6 +15,7 @@ const defaultProtoRootCandidates = [
 ];
 const protoFiles = [
     "axern/control/environment/v1/environment.proto",
+    "axern/control/run/v1/run.proto",
     "axern/control/service/v1/service.proto",
     "axern/control/tunnel/v1/tunnel.proto",
     "axern/node/sandbox/v1/node.proto",

package/dist/proto/axern/control/gateway/v1/gateway.proto

@@ -44,6 +44,13 @@ message ResolveAllocationTerminalRequest {
   int64 ttl_seconds = 2;
   string client_certificate_fingerprint = 3;
   string rollout_execution_lease = 4;
+  AllocationAccessPurpose purpose = 5;
+}
+
+enum AllocationAccessPurpose {
+  ALLOCATION_ACCESS_PURPOSE_UNSPECIFIED = 0;
+  ALLOCATION_ACCESS_PURPOSE_INTERACTIVE = 1;
+  ALLOCATION_ACCESS_PURPOSE_RUN_OUTPUT = 2;
 }
 
 message ResolveAllocationTerminalResponse {

package/dist/proto/axern/control/run/v1/run.proto

@@ -34,6 +34,9 @@ message Run {
   bool exit_code_known = 13;
   string message = 14;
   axern.control.common.v1.WorkloadDiagnosticCode diagnostic_code = 15;
+  // Reserved for durable output metadata once output retention is owned by
+  // the control plane rather than inferred from a node-local allocation.
+  reserved 16 to 18;
 }
 
 message RunListFilter {
@@ -63,6 +66,15 @@ message GetRunResponse {
   Run run = 1;
 }
 
+message WatchRunRequest {
+  string run_id = 1;
+  int64 after_version = 2;
+}
+
+message WatchRunResponse {
+  Run run = 1;
+}
+
 message ListRunsRequest {
   RunListFilter filter = 1;
 }
@@ -83,6 +95,7 @@ message CancelRunResponse {
 service RunControl {
   rpc CreateRun(CreateRunRequest) returns (CreateRunResponse) {}
   rpc GetRun(GetRunRequest) returns (GetRunResponse) {}
+  rpc WatchRun(WatchRunRequest) returns (stream WatchRunResponse) {}
   rpc ListRuns(ListRunsRequest) returns (ListRunsResponse) {}
   rpc CancelRun(CancelRunRequest) returns (CancelRunResponse) {}
 }

package/dist/proto/axern/control/secret/v1/secret.proto

@@ -34,6 +34,7 @@ message SecretListFilter {
 message CreateSecretRequest {
   string namespace = 1;
   SecretType type = 2;
+  // The JSON-encoded map must not exceed 64 KiB. Values are preserved verbatim.
   map<string, string> string_data = 3;
   map<string, string> labels = 4;
 }

package/dist/proto/axern/node/sandbox/v1/node.proto

@@ -199,6 +199,29 @@ message WaitSandboxResponse {
   string message = 4;
 }
 
+enum OutputStream {
+  OUTPUT_STREAM_UNSPECIFIED = 0;
+  OUTPUT_STREAM_STDOUT = 1;
+  OUTPUT_STREAM_STDERR = 2;
+}
+
+message ReadOutputRequest {
+  string allocation_id = 1;
+  int64 attempt = 2;
+  string execution_lease_token = 3;
+  string cursor = 4;
+  bool follow = 5;
+}
+
+message ReadOutputResponse {
+  OutputStream stream = 1;
+  bytes data = 2;
+  string next_cursor = 3;
+  bool terminal = 4;
+  bool truncated = 5;
+  int64 observed_at_unix_milli = 6;
+}
+
 // Capabilities
 
 message CapabilityStatusRequest {
@@ -620,6 +643,7 @@ service NodeSandbox {
   rpc ExecImage(ExecImageRequest) returns (ExecImageResponse) {}
   rpc ProcessImage(stream ProcessImageRequest) returns (stream ProcessImageResponse) {}
   rpc WaitSandbox(WaitSandboxRequest) returns (WaitSandboxResponse) {}
+  rpc ReadOutput(ReadOutputRequest) returns (stream ReadOutputResponse) {}
   rpc CapabilityStatus(CapabilityStatusRequest) returns (CapabilityStatusResponse) {}
   rpc ProxyHTTP(stream ProxyHTTPRequest) returns (stream ProxyHTTPResponse) {}
   rpc StatFile(StatFileRequest) returns (StatFileResponse) {}

package/dist/version.d.ts

@@ -3,5 +3,5 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const AXERN_VERSION = "0.3.1";
+export declare const AXERN_VERSION = "0.4.0";
 export declare function platformName(): string;

package/dist/version.js

@@ -3,7 +3,7 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-export const AXERN_VERSION = "0.3.1";
+export const AXERN_VERSION = "0.4.0";
 export function platformName() {
     return "axern";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cofy-x/axern-sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "TypeScript SDK for Axern agentic infrastructure and isolated sandboxes",
   "license": "Apache-2.0",
   "repository": {