@cofy-x/axern-sdk 0.2.1 → 0.4.0

package/README.md

@@ -43,7 +43,7 @@ const client = AxernClient.fromContext(
 
 const sandbox = await new Sandbox({
   client,
-  image: "python:3.12-slim",
+  image: "docker.io/library/python:3.12-slim",
   namespace: "typescript-sdk-example",
   tunnel: {
     upstream: "127.0.0.1:8080",

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,7 +15,7 @@ const defaultProtoRootCandidates = [
 ];
 const protoFiles = [
     "axern/control/environment/v1/environment.proto",
-    "axern/control/gateway/v1/gateway.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/admin/v1/access.proto

@@ -0,0 +1,123 @@
+syntax = "proto3";
+
+package axern.control.admin.v1;
+
+option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/control/admin/v1;adminv1";
+
+import "google/protobuf/timestamp.proto";
+
+enum PrincipalKind {
+  PRINCIPAL_KIND_UNSPECIFIED = 0;
+  PRINCIPAL_KIND_HUMAN = 1;
+  PRINCIPAL_KIND_SERVICE = 2;
+}
+
+enum PrincipalStatus {
+  PRINCIPAL_STATUS_UNSPECIFIED = 0;
+  PRINCIPAL_STATUS_ACTIVE = 1;
+  PRINCIPAL_STATUS_DISABLED = 2;
+}
+
+enum AccessScopeType {
+  ACCESS_SCOPE_TYPE_UNSPECIFIED = 0;
+  ACCESS_SCOPE_TYPE_PLATFORM = 1;
+  ACCESS_SCOPE_TYPE_NAMESPACE = 2;
+}
+
+enum AccessRole {
+  ACCESS_ROLE_UNSPECIFIED = 0;
+  ACCESS_ROLE_PLATFORM_ADMIN = 1;
+  ACCESS_ROLE_NAMESPACE_ADMIN = 2;
+  ACCESS_ROLE_NAMESPACE_EDITOR = 3;
+  ACCESS_ROLE_NAMESPACE_VIEWER = 4;
+  ACCESS_ROLE_ROLLOUT_EXECUTOR = 5;
+}
+
+message Principal {
+  string principal_id = 1;
+  string name = 2;
+  string display_name = 3;
+  PrincipalKind kind = 4;
+  PrincipalStatus status = 5;
+  int64 version = 6;
+  google.protobuf.Timestamp created_at = 7;
+  google.protobuf.Timestamp updated_at = 8;
+}
+
+message PrincipalCredential {
+  string credential_id = 1;
+  string principal_id = 2;
+  string fingerprint = 3;
+  google.protobuf.Timestamp certificate_not_after = 4;
+  string label = 5;
+  google.protobuf.Timestamp created_at = 6;
+  google.protobuf.Timestamp revoked_at = 7;
+}
+
+message RoleBinding {
+  string binding_id = 1;
+  string principal_id = 2;
+  AccessScopeType scope_type = 3;
+  string namespace = 4;
+  AccessRole role = 5;
+  string created_by_principal_id = 6;
+  google.protobuf.Timestamp created_at = 7;
+  string revoked_by_principal_id = 8;
+  google.protobuf.Timestamp revoked_at = 9;
+}
+
+message CreatePrincipalRequest {
+  string name = 1;
+  string display_name = 2;
+  PrincipalKind kind = 3;
+}
+message CreatePrincipalResponse { Principal principal = 1; }
+
+message ListPrincipalsRequest {}
+message ListPrincipalsResponse { repeated Principal principals = 1; }
+
+message DisablePrincipalRequest { string principal_id = 1; }
+message DisablePrincipalResponse { Principal principal = 1; }
+
+message AddPrincipalCredentialRequest {
+  string principal_id = 1;
+  bytes certificate_der = 2;
+  string label = 3;
+}
+message AddPrincipalCredentialResponse { PrincipalCredential credential = 1; }
+
+message ListPrincipalCredentialsRequest { string principal_id = 1; }
+message ListPrincipalCredentialsResponse { repeated PrincipalCredential credentials = 1; }
+
+message RevokePrincipalCredentialRequest { string credential_id = 1; }
+message RevokePrincipalCredentialResponse { PrincipalCredential credential = 1; }
+
+message GrantRoleBindingRequest {
+  string principal_id = 1;
+  AccessScopeType scope_type = 2;
+  string namespace = 3;
+  AccessRole role = 4;
+}
+message GrantRoleBindingResponse { RoleBinding binding = 1; }
+
+message ListRoleBindingsRequest {
+  string principal_id = 1;
+  string namespace = 2;
+  bool include_revoked = 3;
+}
+message ListRoleBindingsResponse { repeated RoleBinding bindings = 1; }
+
+message RevokeRoleBindingRequest { string binding_id = 1; }
+message RevokeRoleBindingResponse { RoleBinding binding = 1; }
+
+service AccessAdmin {
+  rpc CreatePrincipal(CreatePrincipalRequest) returns (CreatePrincipalResponse) {}
+  rpc ListPrincipals(ListPrincipalsRequest) returns (ListPrincipalsResponse) {}
+  rpc DisablePrincipal(DisablePrincipalRequest) returns (DisablePrincipalResponse) {}
+  rpc AddPrincipalCredential(AddPrincipalCredentialRequest) returns (AddPrincipalCredentialResponse) {}
+  rpc ListPrincipalCredentials(ListPrincipalCredentialsRequest) returns (ListPrincipalCredentialsResponse) {}
+  rpc RevokePrincipalCredential(RevokePrincipalCredentialRequest) returns (RevokePrincipalCredentialResponse) {}
+  rpc GrantRoleBinding(GrantRoleBindingRequest) returns (GrantRoleBindingResponse) {}
+  rpc ListRoleBindings(ListRoleBindingsRequest) returns (ListRoleBindingsResponse) {}
+  rpc RevokeRoleBinding(RevokeRoleBindingRequest) returns (RevokeRoleBindingResponse) {}
+}

package/dist/proto/axern/control/admin/v1/audit.proto

@@ -14,6 +14,13 @@ enum AdminAuditOperation {
   ADMIN_AUDIT_OPERATION_RETRY_STORAGE_BINDING = 4;
   ADMIN_AUDIT_OPERATION_PURGE_SERVICE = 5;
   ADMIN_AUDIT_OPERATION_RETIRE_NODE = 6;
+  ADMIN_AUDIT_OPERATION_CREATE_PRINCIPAL = 7;
+  ADMIN_AUDIT_OPERATION_DISABLE_PRINCIPAL = 8;
+  ADMIN_AUDIT_OPERATION_ADD_CREDENTIAL = 9;
+  ADMIN_AUDIT_OPERATION_REVOKE_CREDENTIAL = 10;
+  ADMIN_AUDIT_OPERATION_GRANT_ROLE_BINDING = 11;
+  ADMIN_AUDIT_OPERATION_REVOKE_ROLE_BINDING = 12;
+  ADMIN_AUDIT_OPERATION_BOOTSTRAP_ACCESS = 13;
 }
 
 enum AdminAuditTargetType {
@@ -22,6 +29,9 @@ enum AdminAuditTargetType {
   ADMIN_AUDIT_TARGET_TYPE_STORAGE_BINDING = 2;
   ADMIN_AUDIT_TARGET_TYPE_SERVICE = 3;
   ADMIN_AUDIT_TARGET_TYPE_NODE = 4;
+  ADMIN_AUDIT_TARGET_TYPE_PRINCIPAL = 5;
+  ADMIN_AUDIT_TARGET_TYPE_CREDENTIAL = 6;
+  ADMIN_AUDIT_TARGET_TYPE_ROLE_BINDING = 7;
 }
 
 message AdminAuditEvent {
@@ -31,6 +41,7 @@ message AdminAuditEvent {
   string target_id = 4;
   string operator_reason = 5;
   google.protobuf.Timestamp created_at = 6;
+  string actor_principal_id = 7;
 }
 
 message AdminAuditEventFilter {

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

@@ -42,6 +42,15 @@ message ResolveServiceRouteResponse {
 message ResolveAllocationTerminalRequest {
   string allocation_id = 1;
   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 {
@@ -54,7 +63,30 @@ message ResolveAllocationTerminalResponse {
   axern.control.common.v1.ExecutionLease lease = 7;
 }
 
+message ResolveTunnelRelayTargetRequest {
+  string session_id = 1;
+}
+
+message ResolveTunnelRelayTargetResponse {
+  string node_edge_target = 1;
+}
+
+message ResolveServiceReplicaTargetsRequest {
+  string service_id = 1;
+}
+
+message ServiceReplicaTarget {
+  string allocation_id = 1;
+  string node_id = 2;
+}
+
+message ResolveServiceReplicaTargetsResponse {
+  repeated ServiceReplicaTarget replicas = 1;
+}
+
 service GatewayControl {
   rpc ResolveServiceRoute(ResolveServiceRouteRequest) returns (ResolveServiceRouteResponse) {}
   rpc ResolveAllocationTerminal(ResolveAllocationTerminalRequest) returns (ResolveAllocationTerminalResponse) {}
+  rpc ResolveTunnelRelayTarget(ResolveTunnelRelayTargetRequest) returns (ResolveTunnelRelayTargetResponse) {}
+  rpc ResolveServiceReplicaTargets(ResolveServiceReplicaTargetsRequest) returns (ResolveServiceReplicaTargetsResponse) {}
 }

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

@@ -0,0 +1,39 @@
+syntax = "proto3";
+
+package axern.control.identity.v1;
+
+option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/control/identity/v1;identityv1";
+
+import "google/protobuf/timestamp.proto";
+
+message PrincipalIdentity {
+  string principal_id = 1;
+  string name = 2;
+  string display_name = 3;
+  string kind = 4;
+}
+
+message CredentialIdentity {
+  string credential_id = 1;
+  string label = 2;
+  string fingerprint = 3;
+  google.protobuf.Timestamp certificate_not_after = 4;
+}
+
+message EffectiveRole {
+  string role = 1;
+  string scope_type = 2;
+  string namespace = 3;
+}
+
+message WhoAmIRequest {}
+
+message WhoAmIResponse {
+  PrincipalIdentity principal = 1;
+  CredentialIdentity credential = 2;
+  repeated EffectiveRole roles = 3;
+}
+
+service IdentityControl {
+  rpc WhoAmI(WhoAmIRequest) returns (WhoAmIResponse) {}
+}

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/control/tunnel/v1/tunnel.proto

@@ -86,6 +86,8 @@ message TunnelSession {
   google.protobuf.Timestamp last_peer_event_at = 20;
   int64 bytes_in = 21;
   int64 bytes_out = 22;
+  string namespace = 23;
+  string creator_principal_id = 24;
 }
 
 message TunnelSessionEvent {
@@ -129,6 +131,7 @@ message ListTunnelSessionsRequest {
   string allocation_id = 1;
   string node_id = 2;
   bool include_terminal = 3;
+  string namespace = 4;
 }
 
 message ListTunnelSessionsResponse {
@@ -173,16 +176,6 @@ message RenewTunnelSessionResponse {
   TunnelSession session = 1;
 }
 
-message ValidateTunnelPeerRequest {
-  string session_id = 1;
-  TunnelPeerKind peer_kind = 2;
-  string token = 3;
-}
-
-message ValidateTunnelPeerResponse {
-  TunnelSession session = 1;
-}
-
 service TunnelControl {
   rpc CreateTunnelSession(CreateTunnelSessionRequest) returns (CreateTunnelSessionResponse) {}
   rpc GetTunnelSession(GetTunnelSessionRequest) returns (GetTunnelSessionResponse) {}
@@ -191,5 +184,4 @@ service TunnelControl {
   rpc InspectTunnelSession(InspectTunnelSessionRequest) returns (InspectTunnelSessionResponse) {}
   rpc RevokeTunnelSession(RevokeTunnelSessionRequest) returns (RevokeTunnelSessionResponse) {}
   rpc RenewTunnelSession(RenewTunnelSessionRequest) returns (RenewTunnelSessionResponse) {}
-  rpc ValidateTunnelPeer(ValidateTunnelPeerRequest) returns (ValidateTunnelPeerResponse) {}
 }

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.2.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.2.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.2.1",
+  "version": "0.4.0",
   "description": "TypeScript SDK for Axern agentic infrastructure and isolated sandboxes",
   "license": "Apache-2.0",
   "repository": {