computer: Let isolate code read module declarations from cf:computer

[mattzcarey]

Code running on the JavaScript backend can now look up how to call any module it can import. A built-in cf:computer module returns each module's TypeScript declarations and examples, and printing a host export shows its declaration.

import * as git from "ws:git";
import { docs, types } from "cf:computer";

docs();               // every module, one line each
docs(git);            // summary, `declare module "ws:git" { ... }`, examples
types(git.cli);       // one export's declaration, with the types it uses
console.log(git.cli); // function cli(input: { argv: string[]; ... }): Promise<GitCliResult> { [host code] }

Models were guessing how to call host modules. While moving the agents harnesses to Computer, the pi harness needed several tries to get ws:git's cli signature right:

• the exec description gives one line of prose per module, with no argument or return types
• a host module's code runs in the Durable Object, so printing an export showed (...args) => call("host/ws:git", "cli", args), and console.log(namespace) threw, because console output went through String()
• cli("status") and cli(["status"]) ran git with no arguments, so they returned its help text with exit code 0

How it works:

• Declarations. Factories take types (TypeScript declarations keyed by name) and examples. The prebuilt modules declare all their exports, and ws:tools writes each tool's declaration from the description and inputSchema that forAISDKTools and forPiTools now pass through.
• Lookups. The backend renders the declarations once per connection, and the isolate looks them up as data. No host call is made.
• Printing. Each host stub is named after its export and prints like a V8 built-in, with { [host code] } in place of { [native code] }. Console output follows Node.js formatting.
• ws:git errors. A call that passes anything other than one options object, or an argv starting with "git", is refused with the shape the call expects.
• Breaking. The cf:* specifiers are reserved, so configured modules can no longer use them.

Tests ran (npm test in packages/computer). The new end-to-end cases run in workerd under both the legacy and new module registries.

[changeset-bot]

🦋 Changeset detected

Latest commit: ef7acbf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/computer	Minor
@cloudflare/dofs	Minor
@cloudflare/computer-rpc	Minor
@cloudflare/computerd	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[aron-cf]

So excited for this 🥳

I'm not sure about the module name. I don't think it should be ws: prefix (which I also think should become computer: or ext: or something that implies it's an extension. Alternatives ws:debug, ws:runtime, ws:help...

Also I think now I see it, we should just have one function. help(<thing>) that returns docs, types, source...

I could also be convinced that help should just be a global:

import * as git from "ws:git";
export default () => ({
  modules: help().docs,          // every module, one line each
  git: help(git),           // ws:git's interface, summary, declarations, and examples, as markdown
  cli: help(git.cli),      // one export's interface, declaration, with the types it names
  byName: help("ws:git"),  // a specifier works too, even for a module that failed to import
});