ggoodman

Design Rationale

The primary goal is to allow a server to execute complex tool logic that requires multiple interactions with the client (like elicitation or LLM sampling) without maintaining any state between requests. This is achieved by serializing the saga's state into an opaque token that is passed back and forth.

• Server Benefits: Simplifies server implementation, enhances scalability, and improves resilience. A server can be restarted without losing the progress of an in-flight tool call.
• Client Responsibilities: The client acts as the state holder, responsible for driving the saga forward by responding to server requests and passing the state token back.

---

New Protocol Operations

ggoodman

// @ts-check

///<reference types="mocha" />

const assert = require('node:assert/strict');

// Since the source file is TypeScript, we have to require the module itself and
// rely on `npm run build` having been called before running tests. ☹️
const { WellKnownError } = require('./well_known_error');

ggoodman

// @ts-check

const CURLY_OPEN = '{'.charCodeAt(0);
const CURLY_CLOSE = '}'.charCodeAt(0);
const SQUARE_OPEN = '['.charCodeAt(0);
const SQUARE_CLOSE = ']'.charCodeAt(0);
const DOUBLE_QUOTE = '"'.charCodeAt(0);
const CHARACTER_COLON = ':'.charCodeAt(0);
const CHARACTER_COMMA = ','.charCodeAt(0);
const CHARACTER_BACKSLASH = '\\'.charCodeAt(0);

ggoodman

import {
  CachedInputFileSystem,
  FileSystem,
  ResolveContext,
  ResolverFactory,
} from 'enhanced-resolve';
import { build, ImportKind, Loader } from 'esbuild';
import * as Fs from 'fs';
import Module from 'module';
import * as Path from 'path';

ggoodman

The withCleanup helper

Example

const result = await withCleanup(async (defer) => {
  const fileHandle = await getFileHandle();
  defer(() => fileHandle.close());
   
 // Carry on

ggoodman

export interface AsyncLuggageFactory<TLuggage, TTraveler extends {}> {
  (obj: TTraveler): PromiseLike<TLuggage>;
}

export interface AsyncLuggage<TLuggage, TTraveler extends {}> {
  get(obj: TTraveler): Promise<TLuggage>;
}

const swallow = () => undefined;

ggoodman

import * as React from 'react';
import { tw } from 'twind';
import type { Context } from 'twind';
import { css } from 'twind/css';
import { TwindContext } from './internal';

export type StyledIntrinsicFactories = {
  [TIntrinsic in keyof React.ReactHTML]: StyledHTML<TIntrinsic>;
};

ggoodman

//@ts-check
'use strict';

const ChildProcess = require('child_process');
const Events = require('events');
const Path = require('path');

const { watch } = require('chokidar');
const { startService } = require('esbuild');
const Pino = require('pino');

ggoodman

Velcro bundle tracing

I've found it helpful when hacking on Velcro to be able to trace the different operations performed by the sytem. Attached is an example log output when bundling up an index.js file having a dependency on react-ui.

If you eliminate the network (thank you polly.js), the whole thing takes 591ms. 🎉

ggoodman

type PromiseReject = {
  eventName: '@@promiseReject';
  err: unknown;
};

type PromiseResolve<T> = {
  eventName: '@@promiseResolve';
  value: T;
};