ExecEnv

The ExecEnv port: the execution environment of a conversation, built per use from its ID and its agent’s cwd. Tools reach files and processes only through it; prompt sections read it (input.env) to render, for example, the working directory. Without a builder, or when it returns nothing, a conversation has no environment and tools that need one fail cleanly.

Since v0.0.0

utils

EnvError (class)

A failure building an environment.

Signature

declare class EnvError

Since v0.0.0

ExecEnv (interface)

One conversation’s environment: a file system and a shell. A relative path resolves against cwd. Interrupting an operation aborts it; interrupting exec kills the command’s process group.

Signature

export interface ExecEnv {
  /**
   * The file namespace: equal IDs see the same files at the same paths, whatever their `cwd`. Every local Node
   * environment shares one ID; each container or remote host has its own.
   */
  readonly id: string
  /** Absolute working directory. */
  readonly cwd: string
  readonly absolutePath: (path: string) => Effect.Effect<string, FileError>
  readonly joinPath: (parts: ReadonlyArray<string>) => Effect.Effect<string, FileError>
  readonly readTextFile: (path: string) => Effect.Effect<string, FileError>
  /** The first `maxLines` lines (all without it), without their line terminators. */
  readonly readTextLines: (
    path: string,
    options?: { readonly maxLines?: number }
  ) => Effect.Effect<ReadonlyArray<string>, FileError>
  readonly readBinaryFile: (path: string) => Effect.Effect<Uint8Array, FileError>
  /** Write a file, creating parent directories. */
  readonly writeFile: (path: string, content: string | Uint8Array) => Effect.Effect<void, FileError>
  readonly appendFile: (path: string, content: string | Uint8Array) => Effect.Effect<void, FileError>
  readonly renameFile: (source: string, destination: string) => Effect.Effect<void, FileError>
  readonly fileInfo: (path: string) => Effect.Effect<FileInfo, FileError>
  readonly listDir: (path: string) => Effect.Effect<ReadonlyArray<FileInfo>, FileError>
  /** The path with symlinks resolved; `not_found` when it does not exist. */
  readonly canonicalPath: (path: string) => Effect.Effect<string, FileError>
  readonly exists: (path: string) => Effect.Effect<boolean, FileError>
  readonly createDir: (path: string, options?: { readonly recursive?: boolean }) => Effect.Effect<void, FileError>
  readonly remove: (
    path: string,
    options?: { readonly recursive?: boolean; readonly force?: boolean }
  ) => Effect.Effect<void, FileError>
  readonly createTempDir: (prefix?: string) => Effect.Effect<string, FileError>
  readonly createTempFile: (options?: {
    readonly prefix?: string
    readonly suffix?: string
  }) => Effect.Effect<string, FileError>
  /** Run a command through the shell; a nonzero exit is a result, not a failure. */
  readonly exec: (command: string, options?: ExecOptions) => Effect.Effect<ExecResult, ExecError>
}

Since v0.0.0

ExecEnvBuilder (class)

Signature

declare class ExecEnvBuilder

Since v0.0.0

ExecEnvBuilderShape (interface)

Builds environments. It may read committed state (Session), for example an app document naming the conversation’s sandbox. Called at each use and never on the commit line.

Signature

export interface ExecEnvBuilderShape {
  readonly build: (target: Target) => Effect.Effect<Option.Option<ExecEnv>, EnvError, Session>
}

Since v0.0.0

ExecError (class)

A command that could not run to its exit.

Signature

declare class ExecError

Since v0.0.0

ExecErrorCode (type alias)

What running a command failed with.

Signature

type ExecErrorCode = "timeout" | "shell_unavailable" | "spawn_error" | "callback_error" | "unknown"

Since v0.0.0

ExecOptions (interface)

Signature

export interface ExecOptions {
  /** Default: the environment's `cwd`. */
  readonly cwd?: string
  /** Variables to set; with `inheritEnv` (default `true`) on top of the environment's own. */
  readonly env?: Readonly<Record<string, string>>
  readonly inheritEnv?: boolean
  /** Seconds before the command is killed and the call fails with `timeout`. */
  readonly timeout?: number
  /** Every decoded chunk of combined stdout and stderr as it arrives: raw, unbounded and unthrottled. */
  readonly onOutput?: (text: string) => Effect.Effect<void>
  readonly spill?: SpillOptions
}

Since v0.0.0

ExecResult (interface)

Signature

export interface ExecResult {
  readonly exitCode: number
  /** A temporary file holding the complete raw output, when the spill thresholds were exceeded. */
  readonly spillPath?: string
}

Since v0.0.0

FileError (class)

A failed file operation.

Signature

declare class FileError

Since v0.0.0

FileErrorCode (type alias)

What a file operation failed with.

Signature

type FileErrorCode =
  | "aborted"
  | "not_found"
  | "permission_denied"
  | "not_directory"
  | "is_directory"
  | "invalid"
  | "not_supported"
  | "unknown"

Since v0.0.0

FileInfo (interface)

Signature

export interface FileInfo {
  readonly name: string
  readonly path: string
  readonly kind: FileKind
  readonly size: number
  readonly mtimeMs: number
}

Since v0.0.0

FileKind (type alias)

Signature

type FileKind = "file" | "directory" | "symlink"

Since v0.0.0

SpillOptions (interface)

Spill the complete output to a temporary file once it exceeds either threshold.

Signature

export interface SpillOptions {
  readonly afterBytes: number
  /** Complete or partial lines. */
  readonly afterLines: number
}

Since v0.0.0

Target (interface)

What an environment is built for.

Signature

export interface Target {
  readonly conversationId: ConversationId
  /** The agent's `cwd`, when one is set. */
  readonly cwd?: string
}

Since v0.0.0

constant

The same environment for every conversation.

Signature

declare const constant: (env: ExecEnv) => Layer.Layer<ExecEnvBuilder>

Since v0.0.0

layer

Build each conversation’s environment with build; undefined means none.

Signature

declare const layer: (
  build: (target: Target) => Effect.Effect<ExecEnv | undefined, EnvError, Session>
) => Layer.Layer<ExecEnvBuilder>

Since v0.0.0

none

No environment for any conversation.

Signature

declare const none: Layer.Layer<ExecEnvBuilder>

Since v0.0.0

unsupported

An environment where every operation fails with not_supported (exec with shell_unavailable), with overrides on top: for tests and for hosts that only expose a working directory.

Signature

declare const unsupported: (cwd: string, overrides?: Partial<ExecEnv>) => ExecEnv

Since v0.0.0