@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/PluginRuntime.ts

@@ -0,0 +1,414 @@
+import { Cause, Effect, Queue, Redacted, Schema, Stream, pipe } from "effect";
+
+import { HttpClientRequest } from "effect/http";
+
+import * as AuthMethodExecution from "./AuthMethodExecution.ts";
+import * as DualRuntime from "./DualRuntime.ts";
+import { OAuthFlow, OAuthGrantRejected } from "./OAuthFlow.ts";
+import { RemoteRuntime } from "./remote-runtime.ts";
+
+export class PluginExecutionError extends Schema.TaggedError<PluginExecutionError>()(
+  "PluginExecutionError",
+  {
+    category: Schema.Literals(["transport", "runner", "protocol", "cleanup", "artifact-expired"]),
+    cause: Schema.optionalKey(Schema.Redacted(Schema.Defect())),
+    message: Schema.String,
+  },
+) {}
+
+export const maxPayloadBytes = 1024 * 1024;
+export const maxMetadataBytes = 64 * 1024 * 1024;
+/** An Agent Channel result carries a read asset of up to 14 MiB. */
+export const maxChannelResultBytes = 16 * 1024 * 1024;
+export const cancellationTimeout = "5 seconds";
+
+/** The listener half of a Node or Bun IPC channel: a process or a child process. */
+export interface IpcEvents {
+  readonly on: (event: string, listener: (value: unknown) => void) => unknown;
+  readonly removeListener: (event: string, listener: (value: unknown) => void) => unknown;
+}
+
+/** The sending half of a Node or Bun IPC channel: a process or a child process. */
+export interface IpcSender {
+  readonly connected: boolean;
+  readonly send?: ((message: object) => unknown) | undefined;
+}
+
+/** Receive native Node and Bun IPC messages without interpreting plugin logs. */
+export function ipcMessages(channel: IpcEvents) {
+  return Stream.callback<unknown, PluginExecutionError>(queue => {
+    const message = (value: unknown) => {
+      Queue.offerUnsafe(queue, value);
+    };
+    const disconnected = () => {
+      Queue.endUnsafe(queue);
+    };
+    const failed = (cause: unknown) => {
+      Queue.failCauseUnsafe(
+        queue,
+        Cause.fail(
+          PluginExecutionError.make({
+            category: "runner",
+            cause: Redacted.make(cause),
+            message: "Plugin IPC channel failed",
+          }),
+        ),
+      );
+    };
+    return Effect.acquireRelease(
+      Effect.sync(() => {
+        channel.on("message", message);
+        channel.on("disconnect", disconnected);
+        channel.on("error", failed);
+      }),
+      () =>
+        Effect.sync(() => {
+          channel.removeListener("message", message);
+          channel.removeListener("disconnect", disconnected);
+          channel.removeListener("error", failed);
+        }),
+    );
+  });
+}
+
+/** Queue a JSON message; the runtime reports asynchronous send failures through its error event. */
+export function sendIpc(channel: IpcSender, value: object) {
+  return Effect.try({
+    try: () => {
+      if (!channel.connected || channel.send === undefined) {
+        throw PluginExecutionError.make({
+          category: "runner",
+          message: "Plugin IPC channel is closed",
+        });
+      }
+      channel.send(value);
+    },
+    catch: cause =>
+      PluginExecutionError.make({
+        category: "runner",
+        cause: Redacted.make(cause),
+        message: "Cannot send plugin IPC message",
+      }),
+  });
+}
+
+export type OAuthContinuation = typeof OAuthContinuation.Type;
+export const OAuthContinuation = Schema.Struct({
+  expiresAt: Schema.DateFromString,
+  pkceVerifier: Schema.NullOr(Schema.String),
+  redirectUri: Schema.String,
+  state: Schema.String,
+});
+
+export type OAuthStarted = typeof OAuthStarted.Type;
+export const OAuthStarted = Schema.Struct({
+  authorizationUrl: Schema.String,
+  continuation: OAuthContinuation,
+});
+
+const oauth = {
+  authMethodId: Schema.NonEmptyString,
+  providerId: Schema.NonEmptyString,
+  setup: Schema.optionalKey(Schema.Json),
+};
+
+/** The origins a Connection's credential may reach from a run sandbox, and the headers one request gets. */
+export type SandboxAccessResult = typeof SandboxAccessResult.Type;
+export const SandboxAccessResult = Schema.Struct({
+  headers: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+  origins: Schema.Array(Schema.String),
+});
+
+export type AuthRequest = typeof AuthRequest.Type;
+export const AuthRequest = Schema.TaggedStruct("auth", {
+  identity: RemoteRuntime.Identity,
+  operation: Schema.Union([
+    AuthMethodExecution.JsonRequest,
+    Schema.TaggedStruct("oauthStart", { ...oauth, redirectUri: Schema.String }),
+    Schema.TaggedStruct("oauthComplete", {
+      ...oauth,
+      continuation: OAuthContinuation,
+      query: Schema.Record(Schema.String, Schema.String),
+    }),
+    // Without `request`, only the origins; with it, the headers the plugin adds to that request.
+    Schema.TaggedStruct("sandboxAccess", {
+      ...oauth,
+      material: Schema.Json,
+      request: Schema.optionalKey(
+        Schema.Struct({
+          headers: Schema.Record(Schema.String, Schema.String),
+          method: Schema.Literals([
+            "GET",
+            "POST",
+            "PUT",
+            "DELETE",
+            "PATCH",
+            "HEAD",
+            "OPTIONS",
+            "TRACE",
+            "QUERY",
+          ]),
+          url: Schema.String,
+        }),
+      ),
+    }),
+  ]),
+});
+
+/** Decode an Agent Channel's settings outside any tenant, as publication validates them. */
+export type ChannelSettingsRequest = typeof ChannelSettingsRequest.Type;
+export const ChannelSettingsRequest = Schema.TaggedStruct("channelSettings", {
+  identity: RemoteRuntime.Identity,
+  operation: Schema.TaggedStruct("decodeChannelSettings", {
+    channelId: Schema.NonEmptyString,
+    field: Schema.Literals(["definitionSettings", "deploymentSettings"]),
+    value: Schema.Json,
+  }),
+});
+
+export type ExecutionRequest = typeof ExecutionRequest.Type;
+export const ExecutionRequest = Schema.Union([
+  RemoteRuntime.Request,
+  AuthRequest,
+  ChannelSettingsRequest,
+]);
+
+export type Request = typeof Request.Type;
+export const Request = Schema.Union([
+  ExecutionRequest,
+  Schema.TaggedStruct("extract", { identity: RemoteRuntime.Identity }),
+]);
+
+export type Input = typeof Input.Type;
+export const Input = Schema.Union([
+  Request,
+  Schema.TaggedStruct("cancel", { identity: RemoteRuntime.Identity }),
+]);
+
+export type Output = typeof Output.Type;
+export const Output = Schema.Union([
+  RemoteRuntime.Response,
+  Schema.TaggedStruct("interrupted", { identity: RemoteRuntime.Identity }),
+]);
+
+export function checkMessageSize(value: unknown, maximum: number) {
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength <= maximum) return Effect.void;
+  return Effect.fail(
+    PluginExecutionError.make({
+      category: "protocol",
+      message: "Plugin message exceeds its transport limit",
+    }),
+  );
+}
+
+export const encodeInput = Effect.fnUntraced(function* (input: Input) {
+  const encoded = yield* Schema.encodeEffect(Input)(input);
+  yield* checkMessageSize(encoded, maxPayloadBytes);
+  return encoded;
+});
+
+export const decodeInput = Effect.fnUntraced(function* (input: unknown) {
+  const json = yield* Schema.decodeUnknownEffect(Schema.Json)(input);
+  yield* checkMessageSize(json, maxPayloadBytes);
+  return yield* Schema.decodeUnknownEffect(Input)(json);
+});
+
+export const encodeOutput = Effect.fnUntraced(function* (output: Output, maximum: number) {
+  const encoded = yield* Schema.encodeEffect(Output)(output);
+  yield* checkMessageSize(encoded, maximum);
+  return encoded;
+});
+
+export const decodeOutput = Effect.fnUntraced(function* (output: unknown) {
+  const json = yield* Schema.decodeUnknownEffect(Schema.Json)(output);
+  yield* checkMessageSize(json, maxMetadataBytes);
+  return yield* Schema.decodeUnknownEffect(Output)(json);
+});
+
+export function responseLimit(request: Request) {
+  if ("_tag" in request && request._tag === "extract") return maxMetadataBytes;
+  if ("context" in request && request.operation._tag === "channelExecute") {
+    return maxChannelResultBytes;
+  }
+  return maxPayloadBytes;
+}
+
+export type Invocation = typeof Invocation.Type;
+export const Invocation = Schema.Struct({
+  entrypoint: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]+(?:[./][A-Za-z0-9_-]+)*$/u)),
+  exportName: Schema.String.check(Schema.isPattern(/^[A-Za-z_$][A-Za-z0-9_$]*$/u)),
+  request: Request,
+});
+
+export const encodeRequest = Effect.fnUntraced(function* (request: Request) {
+  const encoded = yield* pipe(
+    Schema.encodeEffect(Schema.fromJsonString(Request))(request),
+    Effect.mapError(cause =>
+      PluginExecutionError.make({
+        cause: Redacted.make(cause),
+        category: "protocol",
+        message: "Invalid plugin request",
+      }),
+    ),
+  );
+  if (new TextEncoder().encode(encoded).byteLength > maxPayloadBytes) {
+    return yield* PluginExecutionError.make({
+      category: "protocol",
+      message: "Plugin request exceeds the 1 MiB transport limit",
+    });
+  }
+  return encoded;
+});
+
+export const readBounded = Effect.fnUntraced(function* <E, R>(
+  input: Stream.Stream<Uint8Array, E, R>,
+  maximum = maxPayloadBytes,
+) {
+  const output = { bytes: Buffer.alloc(maximum), size: 0 };
+  yield* pipe(
+    input,
+    Stream.runForEach(chunk =>
+      Effect.gen(function* () {
+        if (output.size + chunk.byteLength > maximum) {
+          return yield* PluginExecutionError.make({
+            category: "protocol",
+            message: "Plugin payload exceeds its transport limit",
+          });
+        }
+        Buffer.from(chunk).copy(output.bytes, output.size);
+        output.size += chunk.byteLength;
+      }),
+    ),
+    Effect.mapError(cause =>
+      PluginExecutionError.make({
+        cause: Redacted.make(cause),
+        category: "protocol",
+        message: "Cannot read plugin payload",
+      }),
+    ),
+  );
+  return output.bytes.toString("utf8", 0, output.size);
+});
+
+export const verifyResponse = Effect.fnUntraced(function* <Response extends Output>(
+  request: Request,
+  response: Response,
+) {
+  if (
+    response.identity.invocationId !== request.identity.invocationId ||
+    response.identity.artifactDigest !== request.identity.artifactDigest ||
+    response.identity.organizationId !== request.identity.organizationId ||
+    response.identity.pluginKey !== request.identity.pluginKey ||
+    response.identity.pluginVersion !== request.identity.pluginVersion
+  ) {
+    return yield* PluginExecutionError.make({
+      category: "protocol",
+      message: "Plugin result does not match its invocation",
+    });
+  }
+  return response;
+});
+
+const executeAuth = Effect.fnUntraced(
+  function* (request: AuthRequest) {
+    const operation = request.operation;
+    const runtime = yield* DualRuntime.Service;
+    if (operation._tag === "sandboxAccess") {
+      const access = yield* runtime.resolveSandboxAccess({
+        ...operation,
+        encoding: "json",
+        setup: operation.setup,
+      });
+      if (operation.request === undefined) {
+        return yield* Schema.encodeEffect(SandboxAccessResult)({ origins: access.origins });
+      }
+      const authorized = yield* access.authorize(
+        HttpClientRequest.make(operation.request.method)(operation.request.url, {
+          headers: operation.request.headers,
+        }),
+      );
+      return yield* Schema.encodeEffect(SandboxAccessResult)({
+        headers: authorized.headers,
+        origins: access.origins,
+      });
+    }
+    if (operation._tag !== "oauthStart" && operation._tag !== "oauthComplete") {
+      return yield* runtime.executeAuthJson(operation);
+    }
+    const method = yield* runtime.getAuthMethod(operation);
+    const setup = yield* runtime.decodeAuthMethodSetup({
+      ...operation,
+      encoding: "json",
+      setup: operation.setup,
+    });
+    const oauth = yield* OAuthFlow.Service;
+    if (operation._tag === "oauthStart") {
+      return yield* Schema.encodeEffect(OAuthStarted)(
+        yield* oauth.start({ method, redirectUri: operation.redirectUri, setup }),
+      );
+    }
+    const completed = yield* oauth.complete({ ...operation, method, setup });
+    return yield* runtime.executeAuthJson(
+      yield* Schema.decodeUnknownEffect(AuthMethodExecution.JsonRequest)({
+        ...operation,
+        _tag: "prepareOAuth2Tokens",
+        tokens: completed.tokens,
+      }),
+    );
+  },
+  (effect, request) =>
+    pipe(
+      effect,
+      Effect.flatMap(
+        Effect.fnUntraced(function* (value) {
+          const result = { _tag: "success" as const, identity: request.identity };
+          if (value === undefined) return result;
+          return { ...result, value: yield* Schema.decodeUnknownEffect(Schema.Json)(value) };
+        }),
+      ),
+      Effect.catch(error => {
+        const cause = error._tag === "AuthMethodHookError" ? error.cause : error;
+        return Effect.succeed({
+          _tag: "failure" as const,
+          error: {
+            ...RemoteRuntime.failure(error),
+            ...(Schema.is(OAuthGrantRejected)(cause) ? { code: "OAuthGrantRejected" } : {}),
+          },
+          identity: request.identity,
+        });
+      }),
+    ),
+);
+
+const executeChannelSettings = Effect.fnUntraced(
+  function* (request: ChannelSettingsRequest) {
+    const runtime = yield* DualRuntime.Service;
+    const { channelId, field, value } = request.operation;
+    const input = { channelId, value };
+    if (field === "definitionSettings") {
+      return yield* runtime.decodeAgentChannelDefinitionSettings(input);
+    }
+    return yield* runtime.decodeAgentChannelDeploymentSettings(input);
+  },
+  (effect, request) =>
+    pipe(
+      effect,
+      Effect.map(value => ({ _tag: "success", identity: request.identity, value }) as const),
+      Effect.catch(error =>
+        Effect.succeed({
+          _tag: "failure" as const,
+          error: RemoteRuntime.failure(error),
+          identity: request.identity,
+        }),
+      ),
+    ),
+);
+
+/** Execute one request against the plugin built in this process; only the guest runner calls it in production. */
+export const execute = Effect.fnUntraced(function* (request: ExecutionRequest) {
+  if (!("_tag" in request)) return yield* RemoteRuntime.execute(request);
+  if (request._tag === "auth") return yield* executeAuth(request);
+  return yield* executeChannelSettings(request);
+});
+
+export * as PluginRuntime from "./PluginRuntime.ts";

package/src/Runner.ts

@@ -0,0 +1,248 @@
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+
+import {
+  Array,
+  Cause,
+  ConfigProvider,
+  Context,
+  Deferred,
+  Effect,
+  Exit,
+  Fiber,
+  FiberMap,
+  Formatter,
+  Inspectable,
+  Layer,
+  Match,
+  Option,
+  Predicate,
+  Redacted,
+  Schema,
+  Scope,
+  Stdio,
+  Stream,
+  String,
+  pipe,
+} from "effect";
+
+import { FetchHttpClient } from "effect/http";
+
+import * as DualRegistry from "./DualRegistry.ts";
+import * as DualRuntime from "./DualRuntime.ts";
+import { OAuthFlow, oauth2TokenRefresherLayer } from "./OAuthFlow.ts";
+import * as Plugin from "./Plugin.ts";
+import { PluginRuntime } from "./PluginRuntime.ts";
+import { RemoteRuntime } from "./remote-runtime.ts";
+
+const guestOAuth = pipe(
+  oauth2TokenRefresherLayer,
+  Layer.provideMerge(OAuthFlow.layer),
+  Layer.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({}))),
+);
+
+function initializationError(cause: unknown) {
+  // Each hop of the runner maps its failure here; the first error keeps its message.
+  if (Schema.is(PluginRuntime.PluginExecutionError)(cause)) return cause;
+  return PluginRuntime.PluginExecutionError.make({
+    category: "runner",
+    cause: Redacted.make(cause),
+    message:
+      pipe(
+        Match.value(cause),
+        Match.when(Predicate.isString, String.trim),
+        Match.orElse(value =>
+          Formatter.format(Inspectable.toJson(value), { ignoreToString: true, space: 2 }),
+        ),
+      ) || "No error details returned by the plugin.",
+  });
+}
+
+// This executable runs only in the plugin's process, using its own SDK and Effect.
+pipe(
+  Effect.gen(function* () {
+    const guestServices = yield* Effect.context<NodeServices.NodeServices>();
+    const scope = yield* Scope.Scope;
+    const runtimeScope = yield* Scope.fork(scope, "sequential");
+    const failed = yield* Deferred.make<never, PluginRuntime.PluginExecutionError>();
+    const invocations = yield* FiberMap.make<
+      string,
+      RemoteRuntime.Response,
+      PluginRuntime.PluginExecutionError
+    >();
+    const stdio = yield* Stdio.Stdio;
+    const args = yield* Schema.decodeUnknownEffect(
+      Schema.Tuple([
+        Schema.NonEmptyString,
+        Schema.NonEmptyString,
+        Schema.Literals(["inspect", "execute"]),
+        Schema.NonEmptyString,
+      ]),
+    )(yield* stdio.args);
+    const load = yield* Effect.cached(
+      Effect.forkIn(
+        Effect.gen(function* () {
+          const exports = yield* Schema.decodeUnknownEffect(
+            Schema.Record(Schema.String, Schema.Unknown),
+          )(yield* Effect.tryPromise({ try: () => import(args[0]), catch: initializationError }));
+          const plugin = exports[args[1]];
+          if (!Plugin.isPlugin(plugin)) {
+            return yield* PluginRuntime.PluginExecutionError.make({
+              category: "protocol",
+              message: "The configured export is not an integration plugin",
+            });
+          }
+          yield* Effect.try({
+            try: () => Plugin.make(plugin.identifier),
+            catch: initializationError,
+          });
+          const runtime = yield* Effect.cached(
+            Effect.forkIn(
+              pipe(
+                Layer.buildWithScope(
+                  pipe(
+                    // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- Imported plugin requirements are erased; the guest supplies only its own services.
+                    DualRuntime.toLayer(DualRuntime.fromPlugin(plugin, args[3])),
+                    Layer.provideMerge(
+                      Layer.mergeAll(
+                        RemoteRuntime.filesUnavailable,
+                        FetchHttpClient.layer,
+                        guestOAuth,
+                      ),
+                    ),
+                  ),
+                  runtimeScope,
+                ),
+                Effect.provideContext(Context.makeUnsafe<unknown>(guestServices.mapUnsafe)),
+              ),
+              runtimeScope,
+            ),
+          );
+          return { plugin, runtime };
+        }),
+        runtimeScope,
+      ),
+    );
+    const execute = Effect.fnUntraced(function* (request: PluginRuntime.Request) {
+      return yield* pipe(
+        Effect.gen(function* () {
+          const { plugin, runtime } = yield* Fiber.join(yield* load);
+          if (
+            request.identity.pluginKey !== plugin.identifier &&
+            !(args[2] === "inspect" && "_tag" in request && request._tag === "extract")
+          ) {
+            return yield* PluginRuntime.PluginExecutionError.make({
+              category: "protocol",
+              message: "Plugin identity does not match the request",
+            });
+          }
+          if (request.identity.pluginVersion !== args[3])
+            return yield* PluginRuntime.PluginExecutionError.make({
+              category: "protocol",
+              message: "Plugin release does not match the request",
+            });
+          if ("_tag" in request && request._tag === "extract") {
+            return {
+              _tag: "success",
+              identity: request.identity,
+              value: yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Json))(
+                yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown))(
+                  DualRegistry.materializePlugin(plugin, {
+                    version: request.identity.pluginVersion,
+                  }),
+                ),
+              ),
+            } satisfies RemoteRuntime.Response;
+          }
+          return yield* pipe(
+            PluginRuntime.execute(request),
+            Effect.provideContext(yield* Fiber.join(yield* runtime)),
+          );
+        }),
+        Effect.catchCauseIf(
+          cause => !Cause.hasInterrupts(cause),
+          cause =>
+            args[2] === "inspect"
+              ? Effect.fail(initializationError(Cause.squash(cause)))
+              : Effect.succeed({
+                  _tag: "failure",
+                  identity: request.identity,
+                  error: {
+                    category: "initialization",
+                    code: "PluginInitializationFailed",
+                    message: "Cannot initialize the installed plugin",
+                    retryable: false,
+                  },
+                } satisfies RemoteRuntime.Response),
+        ),
+        Effect.mapError(initializationError),
+      );
+    });
+    yield* Effect.raceFirst(
+      pipe(
+        PluginRuntime.ipcMessages(process),
+        Stream.runForEach(
+          Effect.fnUntraced(function* (message) {
+            const input = yield* PluginRuntime.decodeInput(message);
+            const key = yield* Schema.encodeEffect(Schema.fromJsonString(RemoteRuntime.Identity))(
+              input.identity,
+            );
+            if ("_tag" in input && input._tag === "cancel") {
+              const fiber = Option.getOrUndefined(yield* FiberMap.get(invocations, key));
+              if (fiber !== undefined) yield* pipe(Fiber.interrupt(fiber), Effect.forkIn(scope));
+              return;
+            }
+            if (
+              (yield* FiberMap.has(invocations, key)) ||
+              (yield* FiberMap.size(invocations)) >= 16
+            ) {
+              return yield* PluginRuntime.PluginExecutionError.make({
+                category: "protocol",
+                message: "Plugin invocation is duplicate or exceeds concurrency",
+              });
+            }
+            const fiber = yield* FiberMap.run(invocations, key, Effect.scoped(execute(input)));
+            yield* pipe(
+              Effect.gen(function* () {
+                const exit = yield* Fiber.await(fiber);
+                const send = Effect.fnUntraced(function* (output: PluginRuntime.Output) {
+                  const encoded = yield* PluginRuntime.encodeOutput(
+                    output,
+                    PluginRuntime.responseLimit(input),
+                  );
+                  if (args[2] !== "inspect") return yield* PluginRuntime.sendIpc(process, encoded);
+                  // Bun can discard queued data on disconnect; wait for its native send callback.
+                  yield* Effect.callback<void, PluginRuntime.PluginExecutionError>(resume => {
+                    if (process.send === undefined) {
+                      resume(Effect.fail(initializationError("Plugin IPC channel is closed")));
+                      return;
+                    }
+                    process.send(encoded, error => {
+                      if (error !== null) resume(Effect.fail(initializationError(error)));
+                      else resume(Effect.void);
+                    });
+                  });
+                  if (process.connected) process.disconnect();
+                });
+                if (Exit.isSuccess(exit)) return yield* send(exit.value);
+                if (Array.every(exit.cause.reasons, Cause.isInterruptReason)) {
+                  return yield* send({ _tag: "interrupted", identity: input.identity });
+                }
+                return yield* initializationError(Cause.squash(exit.cause));
+              }),
+              Effect.catchCause(cause =>
+                Deferred.fail(failed, initializationError(Cause.squash(cause))),
+              ),
+              Effect.forkIn(scope),
+            );
+          }),
+        ),
+        Effect.mapError(initializationError),
+      ),
+      Deferred.await(failed),
+    );
+  }),
+  Effect.scoped,
+  // @effect-diagnostics-next-line strictEffectProvide:off -- This executable owns the guest process services.
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain({ disableErrorReporting: process.argv[4] !== "inspect" }),
+);

package/src/ToolFile.ts

@@ -0,0 +1,28 @@
+/**
+ * JSON-safe file results that hosts can persist without reconstructing displayed text.
+ *
+ * @since 0.0.0
+ */
+import { Schema as EffectSchema } from "effect";
+
+/**
+ * Complete file content and metadata. Hosts validate the bytes before saving them;
+ * a filename is a suggestion, never a trusted destination path.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const Schema = EffectSchema.TaggedStruct("ToolFile", {
+  contentBase64: EffectSchema.String.annotate({
+    contentEncoding: "base64",
+    description: "Complete file bytes in Base64. Preserve this field without truncation.",
+  }),
+  contentType: EffectSchema.NullOr(EffectSchema.String),
+  filename: EffectSchema.NullOr(EffectSchema.String),
+  sizeBytes: EffectSchema.Natural,
+});
+
+/** @since 0.0.0 @category models */
+export type File = typeof Schema.Type;
+
+export * as ToolFile from "./ToolFile.ts";