Workspace

The workspace library gives an agent access to files and shell commands. Its implementation can use a virtual filesystem or a real computer.

Methods

MethodInputsDescription
bashcommandExecute a shell command.
readpath, offset?, limit?Read file content or a range of lines.
writepath, contentCreate or overwrite a file.
editpath, oldText, newTextReplace one exact occurrence of text.

Agent usage

agent.ts
import { Effect } from "effect"
import { Agent } from "tardie/agent"
import { Actor } from "tardie/core"
import { workspace } from "tardie/libraries"

const program = Effect.gen(function* () {
  const tools = yield* Agent.tools([workspace])
  const context = yield* Agent.compact(Agent.messages)

  return yield* Agent.make({
    system: "Use the workspace to read files and run commands.",
    tools,
    context,
  })
})

export const assistant = Actor.make("assistant", program)

Local

Real filesystem

Use Bun with the local filesystem and shell:

workspace.ts
import { localWorkspace } from "tardie/platform/bun"

export const workspace = localWorkspace({
  directory: "./workspace",
  policy: {
    commandTimeoutMs: 30_000,
    maxOutputChars: 32_768,
    maxReadChars: 32_768,
  },
})

Virtual filesystem

Use Bun to persist a virtual filesystem in SQLite:

workspace.ts
import { virtualWorkspace } from "tardie/platform/bun"

export const workspace = virtualWorkspace({
  filename: ".tardigrade/workspace.sqlite",
  name: "agent-workspace",
  directory: "/workspace",
  network: { mode: "none" },
  policy: { maxFileBytes: 8 * 1024 * 1024 },
})

Remote

Virtual filesystem

Use the current Cloudflare Durable Object's SQLite storage for a virtual workspace:

workspace.ts
import { Effect, Layer } from "effect"
import { DurableStorage, virtualWorkspace } from "tardie/platform/cloudflare"

export const workspace = Layer.unwrap(Effect.map(DurableStorage, storage =>
  virtualWorkspace(storage, {
    name: "agent-workspace",
    directory: "/workspace",
    network: { mode: "none" },
    policy: { maxFileBytes: 8 * 1024 * 1024 },
  }),
))

Real filesystem

Use a Cloudflare container, with a sandbox named for the current thread:

sandbox.ts
import { createWorkspaceObject } from "tardie/platform/cloudflare"

export const Sandbox = createWorkspaceObject({
  directory: "/workspace",
  network: { mode: "none" },
  start: (_env, container) => ({ image: container.images.current! }),
})
workspace.ts
import { Effect, Layer } from "effect"
import { Bindings, HostThread, remoteWorkspace, workspaceObjectName } from "tardie/platform/cloudflare"
import type { Sandbox } from "./sandbox"

interface Env {
  readonly SANDBOX: DurableObjectNamespace<InstanceType<typeof Sandbox>>
}

export const workspace = Layer.unwrap(Effect.gen(function* () {
  const env = yield* Bindings<Env>()
  const thread = yield* HostThread
  return remoteWorkspace(env.SANDBOX.getByName(workspaceObjectName(thread)))
}))

See container workspace setup for the image and Wrangler bindings.

Host wiring

Supply the chosen workspace layer alongside your model layer:

worker.ts
import { Layer } from "effect"
import { host } from "tardie/platform/cloudflare"
import { assistant } from "./agent"
import { model } from "./model"
import { workspace } from "./workspace"

const worker = host(assistant, {
  layer: Layer.mergeAll(model, workspace),
})

export const ActorDO = worker.ActorObject
export const ThreadDO = worker.ThreadObject
export default worker

For the container backend, also export the sandbox from the Worker entrypoint:

worker.ts
export { Sandbox } from "./sandbox"

For Bun host wiring, see Run locally. To define your own service and library, see the concept walkthrough.