@modelprofile.com/flexharness 10.17.0 → 10.18.0

package/ts_chat_harness_server/readme.md

@@ -0,0 +1,91 @@
+A `FlexHarnessChatHub` serves the conversations of one FlexHarness to the `@design.estate/dees-catalog` harness chat in browser tabs, over any transport. `/chat/harness` holds its wire contract and the tab's `FlexHarnessChatClient`; `/chat/harness/typedsocket` carries both over TypedSocket.
+
+```sh
+pnpm add @modelprofile.com/flexharness @design.estate/dees-catalog
+```
+
+```typescript
+import { FlexHarness, createFlexToolPermissionRequester } from '@modelprofile.com/flexharness';
+import {
+  FlexHarnessChatHub,
+  createFlexHarnessChatErrorProjector,
+} from '@modelprofile.com/flexharness/chat/harness/server';
+
+let hub: FlexHarnessChatHub<IEditorContext>;
+const harness = new FlexHarness<IAppScope>({
+  scopeResolver,
+  modelResolver: {
+    resolveModel: (context) => {
+      const turn = hub.turnOf(context.scopeId, context.sessionId)!;
+      return { ...modelSetup, identity, system: buildSystem(turn.context) };
+    },
+  },
+  toolProvider: {
+    provideTools: (context) => {
+      const turn = hub.turnOf(context.scopeId, context.sessionId)!;
+      return {
+        tools: {
+          snapshot: tool({
+            description: 'Look at the page the tab shows.',
+            inputSchema: z.object({}),
+            execute: (input, options) =>
+              hub.runClientTool(turn, { toolCallId: options.toolCallId, name: 'snapshot', input }, {
+                abortSignal: options.abortSignal,
+              }),
+          }),
+        },
+      };
+    },
+  },
+  externalErrorProjector: createFlexHarnessChatErrorProjector(),
+});
+hub = new FlexHarnessChatHub<IEditorContext>({ harness, peers, readContext: parseEditorContext });
+```
+
+The host keeps its harness, models, system prompt, tools and scopes. It authenticates every request and calls the hub with the caller it established: the tab and the scope the tab may reach. A conversation of another scope reads as not found. A tab is named by its scope and its id together: the same tab id in two scopes names two tabs, and `IFlexHarnessChatPeers.find()` receives both. Tab ids are per-page secrets all the same; a page never shares its own.
+
+## Conversations
+
+- `attach(caller)` lists the scope's conversations, newest first, and forgets what the tab followed. A tab attaches after loading and after every reconnect; conversations created, renamed or deleted afterwards reach it as `flexHarnessChatSessions` pushes.
+- `open(caller, { sessionId, subscriptionId })` follows a conversation. Its state reaches the tab as numbered `IFlexHarnessChatUpdate` pushes, starting with a `reset`: changed rows, streamed deltas, status, usage, pending permissions, undo and redo availability, and what became of steers. A tab follows one conversation at a time. An update the tab does not acknowledge makes the next change a `reset`; a tab that sees a gap in `seq` opens the conversation again.
+- `send(caller, { sessionId?, send, context })` starts a conversation without `sessionId`. While a turn runs, the message steers it; one the turn no longer takes waits up to `admissionWaitMs` for the ending turn and starts the next one. `readContext` checks the context the message is sent with; the turn carries it. The composer's model, account and effort choices are not used: the host's model resolver decides from the context.
+- `abort`, `respondToPermission`, `moveHistory` (FlexHarness undo and redo), `renameSession` and `deleteSession` act on a conversation of the caller's scope. An imported conversation can be read, not continued.
+
+Refusals are `FlexHarnessChatRequestError`s with a message for the person in the tab; FlexHarness refusals keep their message. Every other error stays an internal error.
+
+## Turns and tools in the tab
+
+FlexHarness carries no per-prompt context, so the hub binds each turn to the tab that started it and the context it was sent with: `turnOf(scopeId, sessionId)`. A turn stops after `turnTimeoutMs`. `runClientTool(turn, request, options)` sends the call to that tab and answers with its output; it fails with `FlexHarnessChatTabUnavailableError` when the tab is gone or does not answer within `toolTimeoutMs`, and passes on the cancellation of an aborted turn.
+
+`createFlexHarnessChatErrorProjector()` is an `externalErrorProjector` for chat conversations: the host's own projection first, then a tab that is gone, model limits, the provider's HTTP status, and a fixed message, never a provider's response text.
+
+## Tabs and shutdown
+
+The host implements `IFlexHarnessChatPeers.find({ tabId, scopeId })`, which reaches a tab over its current connection. Tabs that are gone and run no turn are forgotten every `sweepIntervalMs`; `forgetTab()` forgets one at once.
+
+`stop()` refuses new requests, closes the subscriptions and clears the timers. Requests under way refuse at their next step: a message whose conversation is still being read or created starts no turn, and a turn whose prompt is being queued is cancelled as soon as the harness admits it. `stop()` cancels every turn the hub started and resolves once the requests under way were refused and those turns ended; the harness stays the host's to dispose.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts_chat_harness_typedsocket/classes.clienttransport.ts

@@ -0,0 +1,87 @@
+import * as plugins from './plugins.js';
+import type {
+  IReq_FlexHarnessChat,
+  IReq_FlexHarnessChatSessions,
+  IReq_FlexHarnessChatTool,
+  IReq_FlexHarnessChatUpdate,
+} from './interfaces.requests.js';
+
+export interface IFlexHarnessChatTypedSocketTransportOptions {
+  /** The tab's TypedSocket client. */
+  typedsocket: plugins.typedsocket.TypedSocket;
+  /** The router the client was created with; the transport adds its push handlers to it. */
+  typedrouter: plugins.typedrequest.TypedRouter;
+  /** The tab: 16 random bytes in hex. Defaults to a new random id for this transport's lifetime. */
+  tabId?: string;
+  /** The opaque credential the server's `resolve` reads, read for every request. */
+  callerToken?: () => string | undefined;
+}
+
+/** 128 random bits as hex; `getRandomValues` works on plain http too, unlike `randomUUID`. */
+const randomTabId = (): string =>
+  Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/** A `FlexHarnessChatClient` transport over the tab's TypedSocket client. */
+export class FlexHarnessChatTypedSocketTransport implements plugins.IFlexHarnessChatClientTransport {
+  public readonly tabId: string;
+
+  private readonly socket: plugins.typedsocket.TypedSocket;
+  private readonly router: plugins.typedrequest.TypedRouter;
+  private readonly callerToken: () => string | undefined;
+
+  constructor(optionsArg: IFlexHarnessChatTypedSocketTransportOptions) {
+    this.socket = optionsArg.typedsocket;
+    this.router = optionsArg.typedrouter;
+    this.tabId = optionsArg.tabId ?? randomTabId();
+    this.callerToken = optionsArg.callerToken ?? (() => undefined);
+  }
+
+  public async request<TMethod extends plugins.TFlexHarnessChatMethod>(
+    methodArg: TMethod,
+    requestArg: plugins.TFlexHarnessChatRequest<TMethod>,
+  ): Promise<plugins.TFlexHarnessChatResponse<TMethod>> {
+    const token = this.callerToken();
+    return this.socket.createTypedRequest<IReq_FlexHarnessChat<TMethod>>(methodArg).fire({
+      ...requestArg,
+      caller: { tabId: this.tabId, ...(token === undefined ? {} : { token }) },
+    });
+  }
+
+  public listen(handlersArg: plugins.IFlexHarnessChatPushHandlers): () => void {
+    const pushes = new plugins.typedrequest.TypedRouter();
+    pushes.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatUpdate>('flexHarnessChatUpdate', async (pushArg) => {
+        handlersArg.update(pushArg);
+        return {};
+      }),
+    );
+    pushes.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatSessions>('flexHarnessChatSessions', async (pushArg) => {
+        handlersArg.sessions(pushArg);
+        return {};
+      }),
+    );
+    pushes.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatTool>('flexHarnessChatTool', async (requestArg, toolsArg) => ({
+        // the server cancels the request when the turn stops or the call times out; the handler then
+        // settles at once, since TypedSocket fails a connection whose handlers outlive their requests
+        output: await handlersArg.tool(requestArg, toolsArg?.abortSignal),
+      })),
+    );
+    return this.router.addTypedRouter(pushes);
+  }
+
+  public onReconnect(callbackArg: () => void): () => void {
+    let wasConnected = true;
+    const subscription = this.socket.statusSubject.subscribe((statusArg) => {
+      if (statusArg !== 'connected') {
+        wasConnected = false;
+        return;
+      }
+      if (wasConnected) return;
+      wasConnected = true;
+      callbackArg();
+    });
+    return () => subscription.unsubscribe();
+  }
+}

package/ts_chat_harness_typedsocket/classes.serverbinding.ts

@@ -0,0 +1,172 @@
+import * as plugins from './plugins.js';
+import type {
+  IFlexHarnessChatCallerPayload,
+  IReq_FlexHarnessChat,
+  IReq_FlexHarnessChatSessions,
+  IReq_FlexHarnessChatTool,
+  IReq_FlexHarnessChatUpdate,
+} from './interfaces.requests.js';
+
+/** The hub requests the binding routes; any `FlexHarnessChatHub` serves them. */
+export type TFlexHarnessChatRequestHandler = Pick<
+  plugins.FlexHarnessChatHub<unknown>,
+  'attach' | 'open' | 'close' | 'send' | 'abort' | 'respondToPermission' | 'moveHistory' | 'renameSession' | 'deleteSession'
+>;
+
+/** The hub and scope a request reaches, as the host established them. */
+export interface IFlexHarnessChatResolvedCaller {
+  hub: TFlexHarnessChatRequestHandler;
+  scopeId: string;
+}
+
+export interface IFlexHarnessChatTypedSocketBindingOptions {
+  /**
+   * Authenticates a request: from the caller payload and the request's TypedSocket context, the hub
+   * and the scope it reaches. Throw a `FlexHarnessChatRequestError` to refuse with a message.
+   */
+  resolve(
+    caller: IFlexHarnessChatCallerPayload,
+    context: plugins.typedsocket.ITypedSocketRequestContext | undefined,
+  ): Promise<IFlexHarnessChatResolvedCaller>;
+  /** The server-owned connection tag that names a tab. Default: `flexHarnessChatTab`. */
+  tag?: string;
+  /** How long an update or a session-list push may wait for the tab. Default: 30 seconds. */
+  pushTimeoutMs?: number;
+}
+
+const TAB_ID_PATTERN = /^[0-9a-f]{32}$/;
+const BAD_REQUEST_MESSAGE = 'The request is malformed. Reload the page and try again.';
+const NOT_READY_MESSAGE = 'The server is not accepting connections yet.';
+
+/** The tag payload that names a tab: its scope and its id, in a fixed key order. */
+const tagPayload = (tabArg: plugins.IFlexHarnessChatCaller): { scopeId: string; tabId: string } => ({
+  scopeId: tabArg.scopeId,
+  tabId: tabArg.tabId,
+});
+
+class TypedSocketChatPeer implements plugins.IFlexHarnessChatPeer {
+  constructor(
+    private readonly socket: plugins.typedsocket.TypedSocket,
+    private readonly connection: plugins.typedsocket.ISmartServeConnectionWrapper,
+    private readonly pushTimeoutMs: number,
+  ) {}
+
+  public async update(pushArg: plugins.IFlexHarnessChatUpdate): Promise<void> {
+    await this.socket
+      .createTypedRequest<IReq_FlexHarnessChatUpdate>('flexHarnessChatUpdate', this.connection, { timeoutMs: this.pushTimeoutMs })
+      .fire(pushArg);
+  }
+
+  public async sessions(pushArg: plugins.IFlexHarnessChatSessionsPush): Promise<void> {
+    await this.socket
+      .createTypedRequest<IReq_FlexHarnessChatSessions>('flexHarnessChatSessions', this.connection, { timeoutMs: this.pushTimeoutMs })
+      .fire(pushArg);
+  }
+
+  public async runTool(
+    requestArg: plugins.IFlexHarnessChatToolRequest,
+    optionsArg: { timeoutMs: number; abortSignal?: AbortSignal },
+  ): Promise<plugins.TJsonValue> {
+    const answer = await this.socket
+      .createTypedRequest<IReq_FlexHarnessChatTool>('flexHarnessChatTool', this.connection, optionsArg)
+      .fire(requestArg);
+    return answer.output;
+  }
+}
+
+/**
+ * Serves a `FlexHarnessChatHub` over TypedSocket. Add `typedrouter` to the server's router, hand
+ * the server's TypedSocket to `setTypedSocket()` once it runs, and give the hub `peers`. A tab's
+ * connection carries the server-owned tag with its tab id; every request claims it again.
+ */
+export class FlexHarnessChatTypedSocketBinding implements plugins.IFlexHarnessChatPeers {
+  public readonly typedrouter = new plugins.typedrequest.TypedRouter();
+
+  private readonly resolveCaller: IFlexHarnessChatTypedSocketBindingOptions['resolve'];
+  private readonly tag: string;
+  private readonly pushTimeoutMs: number;
+  private socket: plugins.typedsocket.TypedSocket | null = null;
+
+  constructor(optionsArg: IFlexHarnessChatTypedSocketBindingOptions) {
+    this.resolveCaller = optionsArg.resolve;
+    this.tag = optionsArg.tag ?? 'flexHarnessChatTab';
+    this.pushTimeoutMs = optionsArg.pushTimeoutMs ?? 30 * 1000;
+    this.route<'flexHarnessChatAttach'>('flexHarnessChatAttach', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.attach(caller)));
+    this.route<'flexHarnessChatOpen'>('flexHarnessChatOpen', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.open(caller, request)));
+    this.route<'flexHarnessChatClose'>('flexHarnessChatClose', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.close(caller, request)));
+    this.route<'flexHarnessChatSend'>('flexHarnessChatSend', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.send(caller, request)));
+    this.route<'flexHarnessChatAbort'>('flexHarnessChatAbort', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.abort(caller, request)));
+    this.route<'flexHarnessChatPermission'>('flexHarnessChatPermission', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.respondToPermission(caller, request)));
+    this.route<'flexHarnessChatHistory'>('flexHarnessChatHistory', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.moveHistory(caller, request)));
+    this.route<'flexHarnessChatSessionUpdate'>('flexHarnessChatSessionUpdate', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.renameSession(caller, request)));
+    this.route<'flexHarnessChatSessionDelete'>('flexHarnessChatSessionDelete', (request, tools) =>
+      this.serve(request.caller, tools, (hub, caller) => hub.deleteSession(caller, request)));
+  }
+
+  /** The server's TypedSocket; it exists once the server runs. */
+  public setTypedSocket(socketArg: plugins.typedsocket.TypedSocket): void {
+    this.socket = socketArg;
+  }
+
+  /** The tab's current connection in its scope, as the hub reaches it. */
+  public async find(tabArg: plugins.IFlexHarnessChatCaller): Promise<plugins.IFlexHarnessChatPeer | null> {
+    if (!this.socket) return null;
+    const connection = await this.socket.findTargetConnectionByTag(this.tag, tagPayload(tabArg));
+    return connection ? new TypedSocketChatPeer(this.socket, connection, this.pushTimeoutMs) : null;
+  }
+
+  private route<TMethod extends plugins.TFlexHarnessChatMethod>(
+    methodArg: TMethod,
+    handlerArg: plugins.typedrequest.THandlerFunction<IReq_FlexHarnessChat<TMethod>>,
+  ): void {
+    this.typedrouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChat<TMethod>>(methodArg, handlerArg));
+  }
+
+  /** Authenticates a request, claims its connection for the tab and runs it on the resolved hub. */
+  private async serve<T>(
+    payloadArg: IFlexHarnessChatCallerPayload | undefined,
+    contextArg: plugins.typedsocket.ITypedSocketRequestContext | undefined,
+    runArg: (hubArg: TFlexHarnessChatRequestHandler, callerArg: plugins.IFlexHarnessChatCaller) => Promise<T>,
+  ): Promise<T> {
+    try {
+      if (!payloadArg || typeof payloadArg.tabId !== 'string' || !TAB_ID_PATTERN.test(payloadArg.tabId)) {
+        throw new plugins.FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
+      }
+      const resolved = await this.resolveCaller(payloadArg, contextArg);
+      const caller = { tabId: payloadArg.tabId, scopeId: resolved.scopeId };
+      await this.claim(contextArg, caller);
+      return await runArg(resolved.hub, caller);
+    } catch (error) {
+      if (error instanceof plugins.FlexHarnessChatRequestError) {
+        throw new plugins.typedrequest.TypedResponseError(error.message);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Marks the connection the request came in on as the tab's, and only that one. The tag names the
+   * tab in its resolved scope, so a caller of another scope that sends the same tab id names a tab
+   * of its own and never reaches this one's connection.
+   */
+  private async claim(
+    contextArg: plugins.typedsocket.ITypedSocketRequestContext | undefined,
+    tabArg: plugins.IFlexHarnessChatCaller,
+  ): Promise<void> {
+    if (!this.socket) throw new plugins.FlexHarnessChatRequestError(NOT_READY_MESSAGE);
+    const connection = this.socket.getServerConnectionForRequest(contextArg);
+    const payload = tagPayload(tabArg);
+    for (const other of await this.socket.findAllTargetConnectionsByTag(this.tag, payload)) {
+      if (other.peer !== connection.peer) this.socket.removeServerTag(other, this.tag);
+    }
+    this.socket.setServerTag(connection, this.tag, payload);
+  }
+}

package/ts_chat_harness_typedsocket/index.ts

@@ -0,0 +1,17 @@
+export {
+  FlexHarnessChatTypedSocketBinding,
+  type IFlexHarnessChatResolvedCaller,
+  type IFlexHarnessChatTypedSocketBindingOptions,
+  type TFlexHarnessChatRequestHandler,
+} from './classes.serverbinding.js';
+export {
+  FlexHarnessChatTypedSocketTransport,
+  type IFlexHarnessChatTypedSocketTransportOptions,
+} from './classes.clienttransport.js';
+export type {
+  IFlexHarnessChatCallerPayload,
+  IReq_FlexHarnessChat,
+  IReq_FlexHarnessChatSessions,
+  IReq_FlexHarnessChatTool,
+  IReq_FlexHarnessChatUpdate,
+} from './interfaces.requests.js';

package/ts_chat_harness_typedsocket/interfaces.requests.ts

@@ -0,0 +1,40 @@
+import type * as plugins from './plugins.js';
+
+/** Who sends a request: the tab, and an opaque credential the host's `resolve` reads. */
+export interface IFlexHarnessChatCallerPayload {
+  /**
+   * The tab: 16 random bytes in hex, kept for the tab's lifetime and never shared. Every request
+   * claims the connection it arrives on for the tab, so pushes and tool calls follow a reconnect.
+   */
+  tabId: string;
+  token?: string;
+}
+
+/** A tab's request to the hub over TypedSocket. */
+export interface IReq_FlexHarnessChat<TMethod extends plugins.TFlexHarnessChatMethod>
+  extends plugins.typedrequestInterfaces.ITypedRequest {
+  method: TMethod;
+  request: plugins.TFlexHarnessChatRequest<TMethod> & { caller: IFlexHarnessChatCallerPayload };
+  response: plugins.TFlexHarnessChatResponse<TMethod>;
+}
+
+/** Push: what changed in the conversation a tab follows. */
+export interface IReq_FlexHarnessChatUpdate extends plugins.typedrequestInterfaces.ITypedRequest {
+  method: 'flexHarnessChatUpdate';
+  request: plugins.IFlexHarnessChatUpdate;
+  response: Record<string, never>;
+}
+
+/** Push: changes of the tab's conversation list. */
+export interface IReq_FlexHarnessChatSessions extends plugins.typedrequestInterfaces.ITypedRequest {
+  method: 'flexHarnessChatSessions';
+  request: plugins.IFlexHarnessChatSessionsPush;
+  response: Record<string, never>;
+}
+
+/** Push: run a tool of a turn in the tab; the answer is the tool's output. */
+export interface IReq_FlexHarnessChatTool extends plugins.typedrequestInterfaces.ITypedRequest {
+  method: 'flexHarnessChatTool';
+  request: plugins.IFlexHarnessChatToolRequest;
+  response: { output: plugins.TJsonValue };
+}

package/ts_chat_harness_typedsocket/plugins.ts

@@ -0,0 +1,28 @@
+// @api.global scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedsocket from '@api.global/typedsocket';
+
+export { typedrequest, typedsocket };
+export type * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+
+// @modelprofile.com scope
+import { FlexHarnessChatRequestError } from '@modelprofile.com/flexharness/chat/harness';
+
+export { FlexHarnessChatRequestError };
+export type { TJsonValue } from '@modelprofile.com/flexharness';
+export type {
+  IFlexHarnessChatClientTransport,
+  IFlexHarnessChatPushHandlers,
+  IFlexHarnessChatSessionsPush,
+  IFlexHarnessChatToolRequest,
+  IFlexHarnessChatUpdate,
+  TFlexHarnessChatMethod,
+  TFlexHarnessChatRequest,
+  TFlexHarnessChatResponse,
+} from '@modelprofile.com/flexharness/chat/harness';
+export type {
+  FlexHarnessChatHub,
+  IFlexHarnessChatCaller,
+  IFlexHarnessChatPeer,
+  IFlexHarnessChatPeers,
+} from '@modelprofile.com/flexharness/chat/harness/server';

package/ts_chat_harness_typedsocket/readme.md

@@ -0,0 +1,57 @@
+`/chat/harness` and its hub over TypedSocket: the server routes every request of a tab to a `FlexHarnessChatHub`, and the tab's `FlexHarnessChatClient` sends and receives through its TypedSocket client.
+
+```sh
+pnpm add @modelprofile.com/flexharness @api.global/typedsocket @api.global/typedrequest @api.global/typedrequest-interfaces
+```
+
+The TypedSocket packages are optional peers: `@api.global/typedsocket` `^9.0.2` with `@api.global/typedrequest` `^9.1.0`, the major TypedSocket uses.
+
+```typescript
+// server
+import { FlexHarnessChatTypedSocketBinding } from '@modelprofile.com/flexharness/chat/harness/typedsocket';
+
+const binding = new FlexHarnessChatTypedSocketBinding({
+  // authenticate the request; the scope never comes from the browser
+  resolve: async (caller, context) => ({ hub, scopeId: await scopeOf(caller.token) }),
+});
+hub = new FlexHarnessChatHub({ harness, peers: binding, readContext });
+server.typedrouter.addTypedRouter(binding.typedrouter);
+await server.start();
+binding.setTypedSocket(server.typedsocket);
+
+// tab
+import { FlexHarnessChatClient } from '@modelprofile.com/flexharness/chat/harness';
+import { FlexHarnessChatTypedSocketTransport } from '@modelprofile.com/flexharness/chat/harness/typedsocket';
+
+const transport = new FlexHarnessChatTypedSocketTransport({ typedsocket, typedrouter, callerToken: () => sessionKey });
+const client = new FlexHarnessChatClient({ transport });
+```
+
+Every request carries `caller: { tabId, token? }`. `resolve` reads it and the request's TypedSocket context and returns the hub and scope it reaches; a `FlexHarnessChatRequestError` it throws reaches the tab as a `TypedResponseError` with its message. The tab id is 16 random bytes in hex, kept for the tab's lifetime and never shared: every request claims the connection it arrives on for the tab with the server-owned tag (`flexHarnessChatTab` by default), so updates, list pushes and tool calls follow a reconnect. The tag's payload is the resolved scope and the tab id: a caller of another scope that sends the same tab id names a tab of its own and never takes over this one's connection, its updates or its tool calls. Pushes wait `pushTimeoutMs` (30 seconds) for the tab.
+
+The transport adds its push handlers (`flexHarnessChatUpdate`, `flexHarnessChatSessions`, `flexHarnessChatTool`) to the tab's router and removes them when the client is disposed. A tool call the server cancels settles at once in the tab. A restored connection makes the client attach again.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts_tools/readme.md

@@ -11,6 +11,16 @@ pnpm add @modelprofile.com/flexharness
 See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
 for composition examples and the SmartAI/SmartAgent migration map.
 
+## Filesystem tools
+
+`createFilesystemTools(context, options)` exposes `read_file`, `write_file`, `list_directory` and, unless `includeDelete: false`, `delete_file` over the context's `fs`. `write_file` and `delete_file` ask `context.requestPermission` (`write`, `delete`) before they change anything.
+
+`includeEdit: true` adds `edit_file { path, find, replace, replaceAll? }`. It replaces one exact occurrence of `find`, or every occurrence with `replaceAll`, and refuses a `find` that does not occur or, without `replaceAll`, occurs more than once. The replacement text is literal. It asks for `write` permission before it reads the file, so an edit made while the request waits is kept. It is off by default, so the tools an existing agent sees do not change.
+
+```typescript
+const tools = createFilesystemTools(context, { includeEdit: true });
+```
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).

package/ts_tools/tool.filesystem.ts

@@ -7,6 +7,8 @@ import {
 export interface ICreateFilesystemToolsOptions {
   /** Include delete_file. Default: true. */
   includeDelete?: boolean;
+  /** Include edit_file, which replaces an exact snippet of a file. Default: false. */
+  includeEdit?: boolean;
   /** Maximum output lines before truncating. */
   maxLines?: number;
   /** Maximum output bytes before truncating. */
@@ -110,6 +112,59 @@ export function createFilesystemTools(context: IToolExecutionContext, options: I
     }),
   };
 
+  if (options.includeEdit === true) {
+    tools.edit_file = plugins.tool({
+      description:
+        'Replace an exact snippet of a UTF-8 file in the active workspace. `find` must occur exactly once unless `replaceAll` is set; include enough surrounding text to make it unique. Requires host permission when configured.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('File path'),
+        find: plugins.z.string().min(1).describe('Exact text to replace, copied from the current file'),
+        replace: plugins.z.string().describe('The text to put in its place'),
+        replaceAll: plugins.z
+          .boolean()
+          .optional()
+          .describe('Replace every occurrence instead of exactly one. Default: false'),
+      }),
+      execute: async (
+        {
+          path: filePath,
+          find,
+          replace,
+          replaceAll,
+        }: { path: string; find: string; replace: string; replaceAll?: boolean },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
+        }
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        const invocation = { toolCallId: invocationOptions?.toolCallId, abortSignal };
+        // asked before the file is read: an edit made while the request waits is kept, not overwritten
+        await context.requestPermission?.({
+          type: 'write',
+          title: 'Edit file',
+          metadata: { path: filePath },
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        const content = await context.fs.readFile(filePath, undefined, invocation);
+        const occurrences = content.split(find).length - 1;
+        if (occurrences === 0) {
+          throw new Error(`The text to replace does not occur in ${filePath}.`);
+        }
+        if (occurrences > 1 && replaceAll !== true) {
+          throw new Error(
+            `The text to replace occurs ${occurrences} times in ${filePath}; include more surrounding text or set replaceAll.`,
+          );
+        }
+        const updated = replaceAll === true ? content.split(find).join(replace) : content.replace(find, () => replace);
+        await context.fs.writeFile(filePath, updated, invocation);
+        const replaced = replaceAll === true ? occurrences : 1;
+        return truncate(`Replaced ${replaced} occurrence${replaced === 1 ? '' : 's'} in ${filePath}`);
+      },
+    });
+  }
+
   if (options.includeDelete !== false) {
     tools.delete_file = plugins.tool({
       description: 'Delete a file or empty directory in the active workspace. Requires host permission when configured.',