@opencode-ai/ai 0.0.0-beta-17492

package/dist/testing.js

@@ -0,0 +1,88 @@
+export * as TestLLM from "./testing.js";
+import { LLMClient } from "./route/client.js";
+import { LLMEvent, LLMResponse, } from "./schema/index.js";
+import { Context, Deferred, Effect, Latch, Layer, Queue, Scope, Stream } from "effect";
+export class Service extends Context.Service()("@opencode/ai/TestLLM") {
+}
+export const complete = (options, ...events) => [
+    LLMEvent.stepStart({ index: 0 }),
+    ...events,
+    LLMEvent.stepFinish({ index: 0, reason: options.reason, usage: options.usage }),
+    LLMEvent.finish({ reason: options.reason }),
+];
+export const stop = (...events) => complete({ reason: { normalized: "stop" } }, ...events);
+export const toolCalls = (...events) => complete({ reason: { normalized: "tool-calls" } }, ...events);
+const textEvents = (value, id) => [
+    LLMEvent.textStart({ id }),
+    LLMEvent.textDelta({ id, text: value }),
+    LLMEvent.textEnd({ id }),
+];
+export const text = (value, id) => stop(...textEvents(value, id));
+export const textWithUsage = (value, id, inputTokens) => complete({ reason: { normalized: "stop" }, usage: { inputTokens, nonCachedInputTokens: inputTokens } }, ...textEvents(value, id));
+export const tool = (id, name, input) => toolCalls(LLMEvent.toolCall({ id, name, input }));
+export const failAfter = (error, ...events) => Stream.fromIterable(events).pipe(Stream.concat(Stream.fail(error)));
+export const hangAfter = (...events) => Stream.concat(Stream.fromIterable(events), Stream.never);
+const toStream = (response) => (Stream.isStream(response) ? response : Stream.fromIterable(response));
+export const layer = (options = {}) => Layer.effect(Service, Effect.gen(function* () {
+    const requests = [];
+    const responses = [];
+    let started = Deferred.makeUnsafe();
+    let fallback = options.fallback;
+    let activeGate;
+    const wait = (count) => Effect.suspend(() => requests.length >= count ? Effect.void : Deferred.await(started).pipe(Effect.andThen(wait(count))));
+    const stream = ((request) => {
+        requests.push(options.transformRequest?.(request) ?? request);
+        const waiting = started;
+        started = Deferred.makeUnsafe();
+        Deferred.doneUnsafe(waiting, Effect.void);
+        const response = responses.shift() ?? fallback;
+        if (!response)
+            return Stream.die(new Error(`TestLLM has no response for request ${requests.length}`));
+        const streamed = toStream(response);
+        const gate = activeGate;
+        if (!gate)
+            return streamed;
+        return Stream.unwrap(Queue.offer(gate.started, undefined).pipe(Effect.andThen(gate.release.await), Effect.as(streamed)));
+    });
+    const client = LLMClient.Service.of({
+        stream,
+        generate: (request) => stream(request).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce), Effect.flatMap((state) => {
+            const response = LLMResponse.complete(state);
+            if (response)
+                return Effect.succeed(response);
+            return Effect.die("TestLLM response ended without a terminal finish event");
+        })),
+    });
+    return Service.of({
+        requests,
+        push: (...input) => Effect.sync(() => {
+            responses.push(...input);
+        }),
+        always: (response) => Effect.sync(() => {
+            fallback = response;
+        }),
+        wait,
+        gate: Effect.gen(function* () {
+            const gate = {
+                started: yield* Effect.acquireRelease(Queue.unbounded(), Queue.shutdown),
+                release: yield* Latch.make(),
+            };
+            activeGate = gate;
+            const release = Effect.sync(() => {
+                if (activeGate === gate)
+                    activeGate = undefined;
+            }).pipe(Effect.andThen(gate.release.open), Effect.asVoid);
+            yield* Effect.addFinalizer(() => release);
+            return {
+                started: Queue.take(gate.started),
+                release,
+            };
+        }),
+        client,
+    });
+}));
+export const clientLayer = Layer.effect(LLMClient.Service, Effect.map(Service, (service) => service.client));
+export const push = (...responses) => Service.use((service) => service.push(...responses));
+export const always = (response) => Service.use((service) => service.always(response));
+export const wait = (count) => Service.use((service) => service.wait(count));
+export const gate = Service.use((service) => service.gate);

package/dist/tool-runtime.d.ts

@@ -0,0 +1,15 @@
+import { Effect } from "effect";
+import { LLMEvent, type ToolCallPart, type ToolOutput as ToolOutputType, type ToolResultValue as ToolResultValueType } from "./schema/index.js";
+import { type Tools } from "./tool.js";
+export interface ToolSettlement {
+    readonly result: ToolResultValueType;
+    readonly output?: ToolOutputType;
+}
+export interface DispatchResult extends ToolSettlement {
+    readonly events: ReadonlyArray<LLMEvent>;
+}
+/** Execute one canonical tool call without owning provider IO or continuation. */
+export declare const dispatch: (tools: Tools, call: ToolCallPart) => Effect.Effect<DispatchResult>;
+export declare const ToolRuntime: {
+    readonly dispatch: (tools: Tools, call: ToolCallPart) => Effect.Effect<DispatchResult>;
+};

package/dist/tool-runtime.js

@@ -0,0 +1,54 @@
+import { Effect } from "effect";
+import { LLMEvent, ToolFailure, ToolOutput, ToolResultValue, } from "./schema/index.js";
+import {} from "./tool.js";
+/** Execute one canonical tool call without owning provider IO or continuation. */
+export const dispatch = (tools, call) => {
+    const tool = tools[call.name];
+    if (!tool)
+        return Effect.succeed(result(call, { type: "error", value: `Unknown tool: ${call.name}` }));
+    if (!tool.execute)
+        return Effect.succeed(result(call, { type: "error", value: `Tool has no execute handler: ${call.name}` }));
+    return decodeAndExecute(tool, call).pipe(Effect.map((value) => result(call, value)), Effect.catchTag("Tool.Error", (failure) => Effect.succeed(result(call, { type: "error", value: failure.message }, failure.error))));
+};
+const decodeAndExecute = (tool, call) => tool._decode(call.input).pipe(Effect.mapError((error) => new ToolFailure({ message: `Invalid tool input: ${error.message}` })), Effect.flatMap((decoded) => tool.execute(decoded, { id: call.id, name: call.name }).pipe(Effect.flatMap((value) => tool._encode(value).pipe(Effect.mapError((error) => new ToolFailure({
+    message: `Tool returned an invalid value for its success schema: ${error.message}`,
+})))), Effect.map((encoded) => {
+    if (tool._legacyResult && ToolResultValue.is(encoded))
+        return { result: encoded, output: ToolOutput.fromResultValue(encoded) };
+    const output = tool._project(decoded, call.id, encoded);
+    const result = ToolOutput.toResultValue(output);
+    return result.type === "error" ? { result } : { result, output };
+}))));
+const result = (call, value, error) => {
+    const settlement = ToolResultValue.is(value) ? { result: value } : value;
+    return {
+        result: settlement.result,
+        output: settlement.output,
+        events: settlement.result.type === "error"
+            ? [
+                LLMEvent.toolError({
+                    id: call.id,
+                    name: call.name,
+                    message: String(settlement.result.value),
+                    error,
+                    providerMetadata: call.providerMetadata,
+                }),
+                LLMEvent.toolResult({
+                    id: call.id,
+                    name: call.name,
+                    result: settlement.result,
+                    providerMetadata: call.providerMetadata,
+                }),
+            ]
+            : [
+                LLMEvent.toolResult({
+                    id: call.id,
+                    name: call.name,
+                    result: settlement.result,
+                    output: settlement.output,
+                    providerMetadata: call.providerMetadata,
+                }),
+            ],
+    };
+};
+export const ToolRuntime = { dispatch };

package/dist/tool.d.ts

@@ -0,0 +1,135 @@
+import { Effect, JsonSchema, Schema } from "effect";
+import { Tool } from "@opencode-ai/schema/tool";
+import type { ToolCallPart, ToolDefinition as ToolDefinitionClass, ToolOutput as ToolOutputType } from "./schema/index.js";
+import { ToolFailure } from "./schema/index.js";
+/**
+ * Schema constraint for tool parameters / success values: no decoding or
+ * encoding services are allowed. Tools should be self-contained — anything
+ * beyond pure data conversion belongs in the handler closure.
+ */
+export type ToolSchema<T> = Schema.Codec<T, any, never, never>;
+export interface ToolExecuteContext {
+    readonly id: ToolCallPart["id"];
+    readonly name: ToolCallPart["name"];
+}
+export type ToolExecute<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>> = (params: Schema.Schema.Type<Parameters>, context?: ToolExecuteContext) => Effect.Effect<Schema.Schema.Type<Success>, ToolFailure>;
+export interface ToolModelOutputInput<Parameters, Output> {
+    readonly id: ToolCallPart["id"];
+    readonly parameters: Parameters;
+    readonly output: Output;
+}
+export type ToolToModelOutput<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>> = (input: ToolModelOutputInput<Schema.Schema.Type<Parameters>, Success["Encoded"]>) => ReadonlyArray<Tool.Content>;
+/**
+ * A type-safe LLM tool. Each tool bundles its own description, parameter
+ * Schema and success Schema. The execute handler is optional: omit it when you
+ * only want to expose a tool schema to the model and handle tool calls outside
+ * this package.
+ *
+ * Errors must be expressed as `ToolFailure`. Unmapped errors and defects fail
+ * the stream.
+ *
+ * Internally each tool also carries memoized codecs and a precomputed
+ * `ToolDefinition` so callers do not rebuild them per invocation.
+ */
+export interface Definition<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>> {
+    readonly description: string;
+    readonly parameters: Parameters;
+    readonly success: Success;
+    readonly execute?: ToolExecute<Parameters, Success>;
+    readonly toModelOutput?: ToolToModelOutput<Parameters, Success>;
+    readonly toStructuredOutput?: (output: Success["Encoded"]) => unknown;
+    /** @internal */
+    readonly _decode: (input: unknown) => Effect.Effect<Schema.Schema.Type<Parameters>, Schema.SchemaError>;
+    /** @internal */
+    readonly _encode: (value: Schema.Schema.Type<Success>) => Effect.Effect<unknown, Schema.SchemaError>;
+    /** @internal */
+    readonly _project: (parameters: Schema.Schema.Type<Parameters>, id: ToolCallPart["id"], output: unknown) => ToolOutputType;
+    /** @internal */
+    readonly _legacyResult: boolean;
+    /** @internal */
+    readonly _definition: ToolDefinitionClass;
+}
+export type AnyTool = Definition<any, any>;
+export type ExecutableTool<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>> = Definition<Parameters, Success> & {
+    readonly execute: ToolExecute<Parameters, Success>;
+};
+export type AnyExecutableTool = ExecutableTool<any, any>;
+export type ExecutableTools = Record<string, AnyExecutableTool>;
+/**
+ * Constructs a tool. Two input modes:
+ *
+ * 1. **Typed** — pass Effect `parameters` and `success` Schemas; inputs and
+ *    outputs are statically typed and decoded/encoded automatically.
+ *
+ *    ```ts
+ *    Tool.make({
+ *      description: "Get current weather",
+ *      parameters: Schema.Struct({ city: Schema.String }),
+ *      success: Schema.Struct({ temperature: Schema.Number }),
+ *      execute: ({ city }) => Effect.succeed({ temperature: 22 }),
+ *    })
+ *    ```
+ *
+ * 2. **Dynamic** — pass raw JSON Schema as `jsonSchema`. Use this when the
+ *    schema comes from an external source (MCP server, plugin manifest,
+ *    dynamic config) and is not known at compile time. Inputs are typed as
+ *    `unknown`; the handler is responsible for any validation it needs.
+ *
+ *    ```ts
+ *    Tool.make({
+ *      description: "Look something up",
+ *      jsonSchema: { type: "object", properties: { ... } },
+ *      execute: (params) => Effect.succeed(...),
+ *    })
+ *    ```
+ *
+ * In both modes the produced tool flows through `toDefinitions(...)`
+ * identically.
+ */
+export declare function make<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>>(config: {
+    readonly description: string;
+    readonly parameters: Parameters;
+    readonly success: Success;
+    readonly execute: ToolExecute<Parameters, Success>;
+    readonly toModelOutput?: ToolToModelOutput<Parameters, Success>;
+    readonly toStructuredOutput?: (output: Success["Encoded"]) => unknown;
+}): ExecutableTool<Parameters, Success>;
+export declare function make<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>>(config: {
+    readonly description: string;
+    readonly parameters: Parameters;
+    readonly success: Success;
+    readonly execute?: undefined;
+    readonly toModelOutput?: ToolToModelOutput<Parameters, Success>;
+    readonly toStructuredOutput?: (output: Success["Encoded"]) => unknown;
+}): Definition<Parameters, Success>;
+export declare function make(config: {
+    readonly description: string;
+    readonly jsonSchema: JsonSchema.JsonSchema;
+    readonly outputSchema?: JsonSchema.JsonSchema;
+    readonly execute: (params: unknown, context?: ToolExecuteContext) => Effect.Effect<unknown, ToolFailure>;
+    readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>;
+    readonly toStructuredOutput?: (output: unknown) => unknown;
+}): AnyExecutableTool;
+export declare function make(config: {
+    readonly description: string;
+    readonly jsonSchema: JsonSchema.JsonSchema;
+    readonly outputSchema?: JsonSchema.JsonSchema;
+    readonly execute?: undefined;
+    readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>;
+    readonly toStructuredOutput?: (output: unknown) => unknown;
+}): AnyTool;
+/**
+ * A record of named tools. The record key becomes the tool name on the wire.
+ */
+export type Tools = Record<string, AnyTool>;
+/**
+ * Convert a tools record into the `ToolDefinition[]` shape that
+ * `LLMRequest.tools` expects.
+ *
+ * Tool names come from the record keys, so the per-tool cached
+ * `_definition` is rebuilt with the correct name here. The JSON Schema body
+ * is reused.
+ */
+export declare const toDefinitions: (tools: Tools) => ReadonlyArray<ToolDefinitionClass>;
+export { ToolFailure };
+export * as Tool from "./tool.js";

package/dist/tool.js

@@ -0,0 +1,66 @@
+import { Effect, JsonSchema, Schema } from "effect";
+import { Tool } from "@opencode-ai/schema/tool";
+import { ToolDefinition, ToolFailure, ToolOutput } from "./schema/index.js";
+export function make(config) {
+    if ("jsonSchema" in config) {
+        return {
+            description: config.description,
+            parameters: Schema.Unknown,
+            success: Schema.Unknown,
+            execute: config.execute,
+            toModelOutput: config.toModelOutput,
+            toStructuredOutput: config.toStructuredOutput,
+            _decode: Effect.succeed,
+            _encode: Effect.succeed,
+            _project: (parameters, id, output) => project(config.toModelOutput, config.toStructuredOutput, parameters, id, output),
+            _legacyResult: config.toModelOutput === undefined && config.toStructuredOutput === undefined,
+            _definition: new ToolDefinition({
+                name: "",
+                description: config.description,
+                inputSchema: config.jsonSchema,
+                outputSchema: config.outputSchema,
+            }),
+        };
+    }
+    return {
+        description: config.description,
+        parameters: config.parameters,
+        success: config.success,
+        execute: config.execute,
+        toModelOutput: config.toModelOutput,
+        toStructuredOutput: config.toStructuredOutput,
+        _decode: Schema.decodeUnknownEffect(config.parameters),
+        _encode: Schema.encodeEffect(config.success),
+        _project: (parameters, id, output) => project(config.toModelOutput, config.toStructuredOutput, parameters, id, output),
+        _legacyResult: false,
+        _definition: new ToolDefinition({
+            name: "",
+            description: config.description,
+            inputSchema: toJsonSchema(config.parameters),
+            outputSchema: toJsonSchema(config.success),
+        }),
+    };
+}
+/**
+ * Convert a tools record into the `ToolDefinition[]` shape that
+ * `LLMRequest.tools` expects.
+ *
+ * Tool names come from the record keys, so the per-tool cached
+ * `_definition` is rebuilt with the correct name here. The JSON Schema body
+ * is reused.
+ */
+export const toDefinitions = (tools) => Object.entries(tools).map(([name, item]) => new ToolDefinition({
+    name,
+    description: item._definition.description,
+    inputSchema: item._definition.inputSchema,
+    outputSchema: item._definition.outputSchema,
+}));
+const toJsonSchema = (schema) => {
+    const document = Schema.toJsonSchemaDocument(schema);
+    if (Object.keys(document.definitions).length === 0)
+        return document.schema;
+    return { ...document.schema, $defs: document.definitions };
+};
+const project = (toModelOutput, toStructuredOutput, parameters, id, output) => ToolOutput.make(toStructuredOutput?.(output) ?? output, toModelOutput?.({ id, parameters, output }) ?? (typeof output === "string" ? [{ type: "text", text: output }] : []));
+export { ToolFailure };
+export * as Tool from "./tool.js";

package/dist/utils/record.d.ts

@@ -0,0 +1,2 @@
+/** Plain-record narrowing. Excludes arrays so JSON object checks don't accept tuples as key/value bags. */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/utils/record.js

@@ -0,0 +1,2 @@
+/** Plain-record narrowing. Excludes arrays so JSON object checks don't accept tuples as key/value bags. */
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "version": "0.0.0-beta-17492",
+  "name": "@opencode-ai/ai",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "setup:recording-env": "bun run script/setup-recording-env.ts",
+    "test": "bun test --timeout 30000 --only-failures",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.types.json",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "types": "./dist/testing.d.ts"
+    },
+    "./*": {
+      "import": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@clack/prompts": "1.0.0-alpha.1",
+    "@effect/platform-node": "4.0.0-beta.101",
+    "@opencode-ai/http-recorder": "0.0.0-beta-17492",
+    "@tsconfig/bun": "1.0.9",
+    "@types/bun": "1.3.13",
+    "@typescript/native-preview": "7.0.0-dev.20251207.1",
+    "typescript": "5.8.2"
+  },
+  "dependencies": {
+    "@smithy/eventstream-codec": "4.2.14",
+    "@smithy/util-utf8": "4.2.2",
+    "@opencode-ai/schema": "0.0.0-beta-17492",
+    "aws4fetch": "1.0.20",
+    "effect": "4.0.0-beta.101",
+    "google-auth-library": "10.5.0"
+  }
+}