@declaw/sdk 1.0.2 → 1.0.3

package/dist/index.d.cts

@@ -818,6 +818,19 @@ declare class Filesystem {
     }): Promise<WatchHandle>;
 }
 
+/** Outcome of a PTY session — produced by `PtyHandle.wait()`. */
+interface PtyResult {
+    /** Remote shell exit code. `-1` if the stream dropped before a clean exit frame. */
+    exitCode: number;
+}
+/** Options for attaching to a running PTY via `Pty.connect()`. */
+interface PtyConnectOpts {
+    /**
+     * Callback invoked with every chunk of PTY output as raw bytes.
+     * Optional — omit to drive the stream via the handle's async iterator.
+     */
+    onData?: (data: Uint8Array) => void;
+}
 /** Options for creating a PTY session. */
 interface PtyCreateOpts {
     /** Terminal size. Defaults to { cols: 80, rows: 24 }. */
@@ -828,7 +841,11 @@ interface PtyCreateOpts {
     cwd?: string;
     /** Environment variables. */
     envs?: Record<string, string>;
-    /** Command timeout in seconds. */
+    /**
+     * PTY session TTL in seconds. Defaults to 3600 (1 hour). Pass `0` to
+     * keep the session alive indefinitely — it will still die when the
+     * parent sandbox's timeout fires.
+     */
     timeout?: number;
     /** Per-request timeout in milliseconds (applies to the initial create call only). */
     requestTimeout?: number;
@@ -868,8 +885,8 @@ declare class PtyHandle {
      * running server-side and a fresh `stream()` call reattaches.
      */
     disconnect(): void;
-    /** Resolves with the remote exit code when the PTY process exits. */
-    wait(): Promise<number>;
+    /** Resolves with the remote exit result when the PTY process exits. */
+    wait(): Promise<PtyResult>;
     /**
      * Async iterator over raw output chunks. Use when you want to drive
      * the stream yourself:
@@ -894,6 +911,15 @@ declare class Pty {
     private readonly client;
     constructor(sandboxId: string, client: ApiClient);
     create(opts?: PtyCreateOpts): Promise<PtyHandle>;
+    /**
+     * Reattach to an already-running PTY by its pid.
+     *
+     * Returns a fresh `PtyHandle` that streams the live output of the
+     * existing session. Multiple clients can subscribe to the same pid
+     * concurrently — each receives output from the moment it connects
+     * (no scrollback replay).
+     */
+    connect(pid: number, opts?: PtyConnectOpts): PtyHandle;
     kill(pid: number, requestTimeout?: number): Promise<boolean>;
     sendStdin(pid: number, data: Uint8Array | string, requestTimeout?: number): Promise<void>;
     resize(pid: number, size: PtySize, requestTimeout?: number): Promise<void>;
@@ -1382,4 +1408,4 @@ declare class Template {
     static getBuildStatus(buildId: string, opts?: GetBuildStatusOpts): Promise<TemplateBuildStatus>;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry };
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry };

package/dist/index.d.ts

@@ -818,6 +818,19 @@ declare class Filesystem {
     }): Promise<WatchHandle>;
 }
 
+/** Outcome of a PTY session — produced by `PtyHandle.wait()`. */
+interface PtyResult {
+    /** Remote shell exit code. `-1` if the stream dropped before a clean exit frame. */
+    exitCode: number;
+}
+/** Options for attaching to a running PTY via `Pty.connect()`. */
+interface PtyConnectOpts {
+    /**
+     * Callback invoked with every chunk of PTY output as raw bytes.
+     * Optional — omit to drive the stream via the handle's async iterator.
+     */
+    onData?: (data: Uint8Array) => void;
+}
 /** Options for creating a PTY session. */
 interface PtyCreateOpts {
     /** Terminal size. Defaults to { cols: 80, rows: 24 }. */
@@ -828,7 +841,11 @@ interface PtyCreateOpts {
     cwd?: string;
     /** Environment variables. */
     envs?: Record<string, string>;
-    /** Command timeout in seconds. */
+    /**
+     * PTY session TTL in seconds. Defaults to 3600 (1 hour). Pass `0` to
+     * keep the session alive indefinitely — it will still die when the
+     * parent sandbox's timeout fires.
+     */
     timeout?: number;
     /** Per-request timeout in milliseconds (applies to the initial create call only). */
     requestTimeout?: number;
@@ -868,8 +885,8 @@ declare class PtyHandle {
      * running server-side and a fresh `stream()` call reattaches.
      */
     disconnect(): void;
-    /** Resolves with the remote exit code when the PTY process exits. */
-    wait(): Promise<number>;
+    /** Resolves with the remote exit result when the PTY process exits. */
+    wait(): Promise<PtyResult>;
     /**
      * Async iterator over raw output chunks. Use when you want to drive
      * the stream yourself:
@@ -894,6 +911,15 @@ declare class Pty {
     private readonly client;
     constructor(sandboxId: string, client: ApiClient);
     create(opts?: PtyCreateOpts): Promise<PtyHandle>;
+    /**
+     * Reattach to an already-running PTY by its pid.
+     *
+     * Returns a fresh `PtyHandle` that streams the live output of the
+     * existing session. Multiple clients can subscribe to the same pid
+     * concurrently — each receives output from the moment it connects
+     * (no scrollback replay).
+     */
+    connect(pid: number, opts?: PtyConnectOpts): PtyHandle;
     kill(pid: number, requestTimeout?: number): Promise<boolean>;
     sendStdin(pid: number, data: Uint8Array | string, requestTimeout?: number): Promise<void>;
     resize(pid: number, size: PtySize, requestTimeout?: number): Promise<void>;
@@ -1382,4 +1408,4 @@ declare class Template {
     static getBuildStatus(buildId: string, opts?: GetBuildStatusOpts): Promise<TemplateBuildStatus>;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry };
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseWriteInfo, requiresTlsInterception, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry };

package/dist/index.js

@@ -1539,7 +1539,7 @@ var PtyHandle = class {
   disconnect() {
     this.aborter.abort();
   }
-  /** Resolves with the remote exit code when the PTY process exits. */
+  /** Resolves with the remote exit result when the PTY process exits. */
   wait() {
     return this.exitPromise;
   }
@@ -1576,7 +1576,7 @@ var PtyHandle = class {
           const parsed = parseSSEFrame(frame);
           if (!parsed) continue;
           if (parsed.event === "exit") {
-            this.resolveExit(parsed.exitCode ?? -1);
+            this.resolveExit({ exitCode: parsed.exitCode ?? -1 });
             return;
           }
           if (parsed.bytes) {
@@ -1598,7 +1598,7 @@ var PtyHandle = class {
         throw err;
       }
     } finally {
-      this.resolveExit(-1);
+      this.resolveExit({ exitCode: -1 });
     }
   }
 };
@@ -1645,11 +1645,11 @@ var Pty = class {
     const user = opts?.user ?? "user";
     const body = {
       size: { cols: size.cols, rows: size.rows },
-      user
+      user,
+      timeout: opts?.timeout ?? 3600
     };
     if (opts?.cwd !== void 0) body.cwd = opts.cwd;
     if (opts?.envs !== void 0) body.envs = opts.envs;
-    if (opts?.timeout !== void 0) body.timeout = opts.timeout;
     const data = await this.client.post(
       `/sandboxes/${this.sandboxId}/pty`,
       { json: body, timeout: opts?.requestTimeout }
@@ -1657,7 +1657,18 @@ var Pty = class {
     const pid = data.pid;
     return new PtyHandle(pid, this.sandboxId, this.client, opts?.onData);
   }
-  // --- Legacy low-level API (kept for callers that already hold a pid). ---
+  /**
+   * Reattach to an already-running PTY by its pid.
+   *
+   * Returns a fresh `PtyHandle` that streams the live output of the
+   * existing session. Multiple clients can subscribe to the same pid
+   * concurrently — each receives output from the moment it connects
+   * (no scrollback replay).
+   */
+  connect(pid, opts) {
+    return new PtyHandle(pid, this.sandboxId, this.client, opts?.onData);
+  }
+  // --- Low-level API by pid (kept for callers that already hold one). ---
   async kill(pid, requestTimeout) {
     const data = await this.client.delete(
       `/sandboxes/${this.sandboxId}/pty/${pid}`,