Workspace Runtime Execution

session.sendText(...) asks an Agent to reason and act. workspace.run(...) lets the application execute code it already knows should run. For a deterministic operation, the application need not spend an Agent round merely to execute it.

const result = await workspace.run(`
  const text = await Deno.readTextFile("data.json");
  const data = JSON.parse(text);
  console.log(JSON.stringify({ count: data.items.length }));
`);

if (result.stdoutTruncated || result.stderrTruncated) {
  throw new Error("Workspace script output was truncated");
}

const value = JSON.parse(result.stdout);

The result exposes stdout, stderr, exit code, and truncation flags. See the PedelecWorkspace reference for the precise result type, non-zero exits, failures, and timeouts.

Direct runs fit an Export button that generates files, loading and normalizing project metadata, preprocessing before sending context to an Agent, validation before save, a known local migration, or building a derived manifest.

Reuse a Runtime Module in one run

import { defineRuntimeModule } from "@kaoruisaac/pedelec";

const projectTools = defineRuntimeModule({
  name: "project-tools",
  entry: "./deno/project-tools.ts",
});

const result = await workspace.run(
  `
    import { buildManifest } from "project-tools";
    await buildManifest();
  `,
  { runtimeModules: [projectTools] },
);

Workspace-only declarations need no Agent-facing description or usage. Modules are supplied explicitly per run; only requested modules are mounted. Pedelec may privately reuse prepared packages while its runtime cache remains valid. There is no public Workspace module registry.

Session / Thread → skills.runtimeModules → Agent-side pedelec-ts-runtime only
Workspace run   → workspace.run({ runtimeModules }) → application execution only

workspace.run() never inherits Session Runtime Modules. Session creation never inherits modules from previous Workspace runs, and Workspace-run modules do not appear in Agent Host Context.

Workspace Runtime execution may run concurrently with Agent/provider work and other workspace.run() calls in the same Workspace. Pedelec does not coordinate filesystem conflicts between those actors. See PedelecWorkspace.