@popcomputer/structured-chat 0.1.0

package/dist/core/tool-set.d.ts

@@ -0,0 +1,49 @@
+import { Effect } from "effect";
+import type { InvalidToolCall, InvalidToolProjection, ModelToolDefinition, QueryToolDefinitionContract, StructuredTool, ToolDefinitionContract, ToolExecution, ToolCall } from "./tool.js";
+import { type JsonValue } from "./json-value.js";
+/** Non-empty tuple of model-callable query or command definitions. */
+export type ModelToolTuple = readonly [
+    ToolDefinitionContract,
+    ...ReadonlyArray<ToolDefinitionContract>
+];
+/** Non-empty tuple accepted by one repeatable closed query set. */
+export type ToolTuple = readonly [
+    QueryToolDefinitionContract,
+    ...ReadonlyArray<QueryToolDefinitionContract>
+];
+type ToolExecutionOf<Tool> = Tool extends StructuredTool<infer _Name, infer _InputSchema, infer ServerResult, infer _Error, infer _Requirements, infer ModelSchema, infer Presenters, infer _Operation> ? ToolExecution<ServerResult, ModelSchema, Presenters> : never;
+type ToolCallOf<Tool> = Tool extends StructuredTool<infer Name, infer InputSchema, infer _ServerResult, infer _Error, infer _Requirements, infer _ModelSchema, infer _Presenters, infer _Operation> ? ToolCall<Name, InputSchema> : never;
+/** Parsed call union accepted by any member of one tool set. */
+export type ToolSetCall<Tools extends ModelToolTuple> = ToolCallOf<Tools[number]>;
+type ToolErrorOf<Tool> = Tool extends StructuredTool<infer _Name, infer _InputSchema, infer _ServerResult, infer Error, infer _Requirements, infer _ModelSchema, infer _Presenters, infer _Operation> ? Error : never;
+type ToolRequirementsOf<Tool> = Tool extends StructuredTool<infer _Name, infer _InputSchema, infer _ServerResult, infer _Error, infer Requirements, infer _ModelSchema, infer _Presenters, infer _Operation> ? Requirements : never;
+/** Execution union produced by any member of a tool set. */
+export type ToolSetExecution<Tools extends ToolTuple> = ToolExecutionOf<Tools[number]>;
+/** Application failure union produced by any member of a tool set. */
+export type ToolSetError<Tools extends ToolTuple> = InvalidToolCall | InvalidToolProjection | ToolErrorOf<Tools[number]>;
+/** Effect services required by any member of a tool set. */
+export type ToolSetRequirements<Tools extends ToolTuple> = ToolRequirementsOf<Tools[number]>;
+/** Planning-only registry shared by query and command stages. */
+export interface ToolCallPlanner<Tools extends ModelToolTuple> {
+    readonly models: ReadonlyArray<ModelToolDefinition>;
+    readonly parseCall: (input: JsonValue) => Effect.Effect<ToolSetCall<Tools>, InvalidToolCall>;
+}
+/** A closed, stage-safe registry of tools that may execute. */
+export interface ToolSet<Tools extends ToolTuple> extends ToolCallPlanner<Tools> {
+    readonly tools: Tools;
+    readonly models: ReadonlyArray<ModelToolDefinition>;
+    /** Strictly parse one call to one registered tool without executing it. */
+    readonly parseCall: (input: JsonValue) => Effect.Effect<ToolSetCall<Tools>, InvalidToolCall>;
+    /** Execute one already-parsed call without decoding its arguments again. */
+    readonly execute: (call: ToolSetCall<Tools>) => Effect.Effect<ToolSetExecution<Tools>, ToolSetError<Tools>, ToolSetRequirements<Tools>>;
+    /** Strictly parse and execute one call to one registered tool. */
+    readonly executeCall: (input: JsonValue) => Effect.Effect<ToolSetExecution<Tools>, ToolSetError<Tools>, ToolSetRequirements<Tools>>;
+}
+/**
+ * Define the complete set of tools available to one model step or chat stage.
+ *
+ * Names must be unique. Unknown, malformed, and out-of-stage calls fail before
+ * application execution begins.
+ */
+export declare const defineToolSet: <const Tools extends ToolTuple>(...tools: Tools) => ToolSet<Tools>;
+export {};

package/dist/core/tool-set.js

@@ -0,0 +1,66 @@
+import { Effect, Schema, unsafeCoerce } from "effect";
+import { InvalidToolCall as InvalidToolCallError, InvalidToolCallReasonSchema, ToolNameSchema, } from "./tool.js";
+import { JsonValueSchema } from "./json-value.js";
+const IncomingToolCallSchema = Schema.Struct({
+    name: ToolNameSchema,
+    arguments: JsonValueSchema,
+});
+const invalidCall = (reason, tool) => new InvalidToolCallError({
+    tool,
+    reason,
+    path: null,
+});
+/**
+ * Define the complete set of tools available to one model step or chat stage.
+ *
+ * Names must be unique. Unknown, malformed, and out-of-stage calls fail before
+ * application execution begins.
+ */
+export const defineToolSet = (...tools) => {
+    const runtimeTools = new Map();
+    for (const tool of tools) {
+        if (tool.operation !== "query") {
+            throw new Error("Repeatable tool sets accept query tools only");
+        }
+        if (runtimeTools.has(tool.name)) {
+            throw new Error(`Duplicate structured chat tool name: ${tool.name}`);
+        }
+        // SAFETY: ToolDefinitionContract carries the package-owned nominal identity.
+        // Runtime execution is erased here and restored by ToolSet's conditional
+        // public result, error, and requirement types.
+        runtimeTools.set(tool.name, unsafeCoerce(tool));
+    }
+    const selectTool = (name) => {
+        const tool = runtimeTools.get(name);
+        if (tool === undefined) {
+            return Effect.fail(invalidCall("unknown_tool", name));
+        }
+        return Effect.succeed(tool);
+    };
+    const parseCallRuntime = (input) => Schema.decodeUnknown(IncomingToolCallSchema)(input, {
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError(() => invalidCall("invalid_envelope", null)), Effect.flatMap((call) => selectTool(call.name).pipe(Effect.flatMap((tool) => tool.parseCall(call)))), Effect.withSpan("popcomputer.structured_chat.tool_set.parse", {
+        attributes: { toolCount: tools.length },
+    }));
+    // SAFETY: the envelope parser establishes a registered name, then that
+    // registered tool parses its own literal name and argument schema.
+    const parseCall = parseCallRuntime;
+    const executeRuntime = (call) => selectTool(call.name).pipe(Effect.flatMap((tool) => tool.execute(call.arguments)), Effect.withSpan("popcomputer.structured_chat.tool_set.execute", {
+        attributes: { toolCount: tools.length },
+    }));
+    // SAFETY: call is a parsed member of ToolSetCall<Tools>; dispatch selects
+    // that member's registered runtime and passes its decoded arguments to the
+    // corresponding Type-side execute operation.
+    const execute = executeRuntime;
+    const executeCall = (input) => parseCall(input).pipe(Effect.flatMap(execute));
+    return {
+        tools,
+        models: tools.map(({ model }) => model),
+        parseCall,
+        execute,
+        // SAFETY: dispatch selects a member of Tools by its unique runtime name.
+        // Each tool parses itself before executing, so the resulting union exactly
+        // matches ToolSetExecution, ToolSetError, and ToolSetRequirements.
+        executeCall: executeCall,
+    };
+};

package/dist/core/tool.d.ts

@@ -0,0 +1,149 @@
+import { Effect, JSONSchema, Pipeable, Schema } from "effect";
+import * as ParseResult from "effect/ParseResult";
+import type { ViewDefinitionContract, ViewInput, ViewPart } from "./view.js";
+import { type StructuredDefinition } from "./definition.js";
+import type { CommandId } from "./command.js";
+import type { JsonValue } from "./json-value.js";
+/** Stable machine-facing name for one structured chat tool. */
+export declare const ToolNameSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Bounded model-facing description for one structured chat tool. */
+export declare const ToolDescriptionSchema: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+/** Safe reason that a model-authored tool call was rejected. */
+export declare const InvalidToolCallReasonSchema: Schema.Literal<["invalid_envelope", "unknown_tool", "invalid_arguments"]>;
+declare const InvalidToolCall_base: Schema.TaggedErrorClass<InvalidToolCall, "InvalidToolCall", {
+    readonly _tag: Schema.tag<"InvalidToolCall">;
+} & {
+    tool: Schema.NullOr<Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>>;
+    reason: Schema.Literal<["invalid_envelope", "unknown_tool", "invalid_arguments"]>;
+    path: Schema.NullOr<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+}>;
+/** A model-authored tool call failed strict parsing. */
+export declare class InvalidToolCall extends InvalidToolCall_base {
+}
+/** Safe reason that an application-owned tool projection was rejected. */
+export declare const InvalidToolProjectionReasonSchema: Schema.Literal<["invalid_model_result", "invalid_view_data"]>;
+declare const InvalidToolProjection_base: Schema.TaggedErrorClass<InvalidToolProjection, "InvalidToolProjection", {
+    readonly _tag: Schema.tag<"InvalidToolProjection">;
+} & {
+    tool: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    target: typeof Schema.String;
+    reason: Schema.Literal<["invalid_model_result", "invalid_view_data"]>;
+}>;
+/** An application-owned model or view projection violated its schema. */
+export declare class InvalidToolProjection extends InvalidToolProjection_base {
+}
+/** Provider-neutral model tool definition derived from Effect Schema. */
+export interface ModelToolDefinition<Name extends string = string> {
+    readonly name: Name;
+    readonly description: string;
+    readonly inputSchema: JSONSchema.JsonSchema7Root;
+}
+/** Whether an executable model capability is repeatable or side-effecting. */
+export type ToolOperation = "query" | "command";
+/** Opaque stable identity supplied when a command executes. */
+export interface CommandExecutionContext {
+    readonly commandId: CommandId;
+}
+/** Minimum runtime shape retained for every structured chat tool. */
+export interface ToolDefinitionContract extends StructuredDefinition<"tool"> {
+    readonly _tag: "StructuredTool";
+    readonly operation: ToolOperation;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Schema.Schema.AnyNoContext;
+    readonly model: ModelToolDefinition;
+}
+/** Minimum runtime shape retained for a repeatable read-only query. */
+export interface QueryToolDefinitionContract extends ToolDefinitionContract {
+    readonly operation: "query";
+}
+/** Minimum runtime shape retained for a side-effecting command. */
+export interface CommandDefinitionContract extends ToolDefinitionContract {
+    readonly operation: "command";
+    readonly parseCall: (input: JsonValue) => Effect.Effect<ToolCall<string, Schema.Schema.AnyNoContext>, InvalidToolCall>;
+}
+/** One model-authored, schema-parsed tool call. */
+export type ToolCall<Name extends string, InputSchema extends Schema.Schema.AnyNoContext> = {
+    readonly name: Name;
+    readonly arguments: Schema.Schema.Type<InputSchema>;
+};
+/** One application-owned view projection attached to a tool. */
+export interface ToolPresenter<ServerResult, View extends ViewDefinitionContract> {
+    readonly view: View;
+    readonly project: (result: ServerResult) => ViewInput<View> | undefined;
+}
+type PresenterView<Presenter> = Presenter extends ToolPresenter<infer _ServerResult, infer View> ? View : never;
+/** View-part union produced by one configured tool. */
+export type ToolViewPart<Presenters extends ReadonlyArray<ToolPresenter<never, ViewDefinitionContract>>> = ViewPart<PresenterView<Presenters[number]>>;
+type ToolModelResult<ModelSchema extends Schema.Schema.AnyNoContext | undefined> = ModelSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ModelSchema> : undefined;
+/** Complete trusted result of one parsed and executed tool call. */
+export interface ToolExecution<ServerResult, ModelSchema extends Schema.Schema.AnyNoContext | undefined, Presenters extends ReadonlyArray<ToolPresenter<ServerResult, ViewDefinitionContract>>> {
+    readonly serverResult: ServerResult;
+    readonly modelResult: ToolModelResult<ModelSchema>;
+    readonly views: ReadonlyArray<ToolViewPart<Presenters>>;
+    readonly [toolExecutionModelContext]: string | undefined;
+}
+interface ToolModelProjection<ServerResult, ModelSchema extends Schema.Schema.AnyNoContext> {
+    readonly schema: ModelSchema;
+    readonly project: (result: ServerResult) => Schema.Schema.Type<ModelSchema>;
+}
+interface ToolRuntime<Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements, ModelSchema extends Schema.Schema.AnyNoContext | undefined, Presenters extends ReadonlyArray<ToolPresenter<ServerResult, ViewDefinitionContract>>, Operation extends ToolOperation> {
+    readonly executeServer: (input: Schema.Schema.Type<InputSchema>, context: Operation extends "command" ? CommandExecutionContext : undefined) => Effect.Effect<ServerResult, Error, Requirements>;
+    readonly modelProjection: ModelSchema extends Schema.Schema.AnyNoContext ? ToolModelProjection<ServerResult, ModelSchema> : undefined;
+    readonly presenters: Presenters;
+    readonly callSchema: Schema.Schema.AnyNoContext;
+    readonly name: Name;
+    readonly description: string;
+    readonly inputSchema: InputSchema;
+    readonly operation: Operation;
+}
+declare const toolRuntime: unique symbol;
+declare const toolExecutionModelContext: unique symbol;
+interface RuntimeToolExecutionContext {
+    readonly [toolExecutionModelContext]?: string | undefined;
+}
+/** @internal Read the bounded model-visible context retained by one execution. */
+export declare const readToolExecutionModelContext: (execution: RuntimeToolExecutionContext) => string | undefined;
+/** One schema-defined, executable, and pipeable query tool. */
+export interface StructuredTool<Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements, ModelSchema extends Schema.Schema.AnyNoContext | undefined = undefined, Presenters extends ReadonlyArray<ToolPresenter<ServerResult, ViewDefinitionContract>> = readonly [], Operation extends ToolOperation = "query"> extends Pipeable.Pipeable, ToolDefinitionContract {
+    readonly name: Name;
+    readonly operation: Operation;
+    readonly inputSchema: InputSchema;
+    readonly callSchema: Schema.Schema<ToolCall<Name, InputSchema>>;
+    readonly model: ModelToolDefinition<Name>;
+    /** Parse an unknown model-authored invocation. */
+    readonly parseCall: (input: JsonValue) => Effect.Effect<ToolCall<Name, InputSchema>, InvalidToolCall>;
+    /** Execute already-parsed arguments and produce trusted projections. */
+    readonly execute: Operation extends "command" ? (input: Schema.Schema.Type<InputSchema>, context: CommandExecutionContext) => Effect.Effect<ToolExecution<ServerResult, ModelSchema, Presenters>, Error | InvalidToolProjection, Requirements> : (input: Schema.Schema.Type<InputSchema>) => Effect.Effect<ToolExecution<ServerResult, ModelSchema, Presenters>, Error | InvalidToolProjection, Requirements>;
+    /** Parse and execute one unknown model-authored invocation. */
+    readonly executeCall: Operation extends "command" ? (input: JsonValue, context: CommandExecutionContext) => Effect.Effect<ToolExecution<ServerResult, ModelSchema, Presenters>, Error | InvalidToolCall | InvalidToolProjection, Requirements> : (input: JsonValue) => Effect.Effect<ToolExecution<ServerResult, ModelSchema, Presenters>, Error | InvalidToolCall | InvalidToolProjection, Requirements>;
+    readonly [toolRuntime]: ToolRuntime<Name, InputSchema, ServerResult, Error, Requirements, ModelSchema, Presenters, Operation>;
+}
+/** One side-effecting capability accepted only by a terminal command stage. */
+export type StructuredCommand<Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements, ModelSchema extends Schema.Schema.AnyNoContext | undefined = undefined, Presenters extends ReadonlyArray<ToolPresenter<ServerResult, ViewDefinitionContract>> = readonly []> = StructuredTool<Name, InputSchema, ServerResult, Error, Requirements, ModelSchema, Presenters, "command">;
+/** Definition input for one read-only structured chat tool. */
+export interface DefineToolInput<Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements> {
+    readonly name: Name;
+    readonly description: string;
+    readonly input: InputSchema;
+    readonly execute: (input: Schema.Schema.Type<InputSchema>) => Effect.Effect<ServerResult, Error, Requirements>;
+}
+/** Definition input for one idempotently executed structured command. */
+export interface DefineCommandInput<Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements> {
+    readonly name: Name;
+    readonly description: string;
+    readonly input: InputSchema;
+    readonly execute: (input: Schema.Schema.Type<InputSchema>, context: CommandExecutionContext) => Effect.Effect<ServerResult, Error, Requirements>;
+}
+/** Define one read-only, schema-validated structured chat tool. */
+export declare const defineTool: <const Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements>(definition: DefineToolInput<Name, InputSchema, ServerResult, Error, Requirements>) => StructuredTool<Name, InputSchema, ServerResult, Error, Requirements>;
+/** Define one side-effecting command requiring a stable idempotency key. */
+export declare const defineCommand: <const Name extends string, InputSchema extends Schema.Schema.AnyNoContext, ServerResult, Error, Requirements>(definition: DefineCommandInput<Name, InputSchema, ServerResult, Error, Requirements>) => StructuredCommand<Name, InputSchema, ServerResult, Error, Requirements>;
+/** Combinators that add optional capabilities to a structured tool. */
+export declare const Tool: {
+    readonly modelResult: <ServerResult, ModelSchema extends Schema.Schema.AnyNoContext>(schema: ModelSchema, project: (result: ServerResult) => Schema.Schema.Type<ModelSchema>) => <Name extends string, InputSchema extends Schema.Schema.AnyNoContext, Error, Requirements, Presenters extends ReadonlyArray<ToolPresenter<ServerResult, ViewDefinitionContract>>, Operation extends ToolOperation>(tool: StructuredTool<Name, InputSchema, ServerResult, Error, Requirements, undefined, Presenters, Operation>) => StructuredTool<Name, InputSchema, ServerResult, Error, Requirements, ModelSchema, Presenters, Operation>;
+    readonly present: <ServerResult, View extends ViewDefinitionContract>(view: View, project: (result: ServerResult) => ViewInput<View> | undefined) => <Name extends string, InputSchema extends Schema.Schema.AnyNoContext, Error, Requirements, ModelSchema extends Schema.Schema.AnyNoContext | undefined, Presenters extends ReadonlyArray<ToolPresenter<ServerResult, ViewDefinitionContract>>, Operation extends ToolOperation>(tool: StructuredTool<Name, InputSchema, ServerResult, Error, Requirements, ModelSchema, Presenters, Operation>) => StructuredTool<Name, InputSchema, ServerResult, Error, Requirements, ModelSchema, readonly [...Presenters, ToolPresenter<ServerResult, View>], Operation>;
+};
+/** Parse failure retained only for documentation of owned schema boundaries. */
+export type ToolBoundaryParseError = ParseResult.ParseError;
+export {};

package/dist/core/tool.js

@@ -0,0 +1,215 @@
+import { Effect, JSONSchema, Pipeable, Schema, unsafeCoerce, } from "effect";
+import * as ParseResult from "effect/ParseResult";
+import { structuredDefinition, } from "./definition.js";
+/** Stable machine-facing name for one structured chat tool. */
+export const ToolNameSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100), Schema.pattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/));
+/** Bounded model-facing description for one structured chat tool. */
+export const ToolDescriptionSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(2_000));
+/** Safe reason that a model-authored tool call was rejected. */
+export const InvalidToolCallReasonSchema = Schema.Literal("invalid_envelope", "unknown_tool", "invalid_arguments");
+/** A model-authored tool call failed strict parsing. */
+export class InvalidToolCall extends Schema.TaggedError()("InvalidToolCall", {
+    tool: Schema.NullOr(ToolNameSchema),
+    reason: InvalidToolCallReasonSchema,
+    path: Schema.NullOr(Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(500))),
+}) {
+}
+/** Safe reason that an application-owned tool projection was rejected. */
+export const InvalidToolProjectionReasonSchema = Schema.Literal("invalid_model_result", "invalid_view_data");
+/** An application-owned model or view projection violated its schema. */
+export class InvalidToolProjection extends Schema.TaggedError()("InvalidToolProjection", {
+    tool: ToolNameSchema,
+    target: Schema.String,
+    reason: InvalidToolProjectionReasonSchema,
+}) {
+}
+const toolRuntime = Symbol("@popcomputer/structured-chat/ToolRuntime");
+const toolExecutionModelContext = Symbol("@popcomputer/structured-chat/ToolExecutionModelContext");
+const ToolExecutionModelContextSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(40_000));
+/** @internal Read the bounded model-visible context retained by one execution. */
+export const readToolExecutionModelContext = (execution) => {
+    // SAFETY: Every execution returned by a StructuredTool is constructed by
+    // makeTool below with this package-private symbol property.
+    const runtime = execution;
+    return runtime[toolExecutionModelContext];
+};
+const parseToolCall = (name, callSchema, input) => Schema.decodeUnknown(callSchema)(input, {
+    onExcessProperty: "error",
+}).pipe(Effect.mapError((error) => {
+    const issue = ParseResult.ArrayFormatter.formatErrorSync(error)[0];
+    const issuePath = issue === undefined || issue.path.length === 0
+        ? "#"
+        : `#/${issue.path.map(String).join("/")}`;
+    return new InvalidToolCall({
+        tool: name,
+        reason: "invalid_arguments",
+        path: issuePath,
+    });
+}));
+const projectModelResult = (tool, projection, result) => {
+    if (projection === undefined) {
+        // SAFETY: The conditional result type is exactly undefined when no model
+        // projection schema is configured.
+        return Effect.succeed(undefined);
+    }
+    const invalidProjection = () => new InvalidToolProjection({
+        tool,
+        target: "model",
+        reason: "invalid_model_result",
+    });
+    return Effect.try({
+        try: () => projection.project(result),
+        catch: invalidProjection,
+    }).pipe(Effect.flatMap((projected) => Schema.validate(projection.schema)(projected, {
+        onExcessProperty: "error",
+    })), Effect.mapError(invalidProjection), 
+    // SAFETY: Schema.validate returned the configured model schema's exact
+    // Type side, which is ToolModelResult<ModelSchema> in this branch.
+    Effect.map((value) => value));
+};
+const encodeToolExecutionModelContext = (tool, projection, modelResult) => {
+    if (projection === undefined) {
+        return Effect.succeed(undefined);
+    }
+    return Schema.encodeUnknown(projection.schema)(modelResult).pipe(Effect.flatMap((encodedResult) => Schema.encodeUnknown(Schema.parseJson())({
+        tool,
+        result: encodedResult,
+    })), Effect.flatMap((context) => Schema.decodeUnknown(ToolExecutionModelContextSchema)(context)), Effect.mapError(() => new InvalidToolProjection({
+        tool,
+        target: "model_context",
+        reason: "invalid_model_result",
+    })));
+};
+const projectViews = (tool, presenters, result) => Effect.forEach(presenters, (presenter) => {
+    const invalidProjection = () => new InvalidToolProjection({
+        tool,
+        target: presenter.view.name,
+        reason: "invalid_view_data",
+    });
+    return Effect.try({
+        try: () => presenter.project(result),
+        catch: invalidProjection,
+    }).pipe(Effect.flatMap((projected) => projected === undefined
+        ? Effect.succeed(undefined)
+        : presenter.view.parseData(projected)), Effect.mapError(invalidProjection));
+}).pipe(Effect.map((parts) => parts.flatMap((part) => part === undefined ? [] : [part])), Effect.map((parts) => {
+    // SAFETY: Every retained part was parsed by the corresponding presenter
+    // view, and the output union is derived from that same presenter tuple.
+    return unsafeCoerce(parts);
+}));
+const makeTool = (runtime) => {
+    // SAFETY: ToolRuntime.callSchema is constructed from this tool's exact
+    // literal name and InputSchema before makeTool is called.
+    const callSchema = runtime.callSchema;
+    const parseCall = (input) => parseToolCall(runtime.name, callSchema, input);
+    const executeRuntime = (input, context) => runtime.executeServer(input, 
+    // SAFETY: command constructors expose a required context while query
+    // constructors expose no context; runtime.operation owns that invariant.
+    unsafeCoerce(context)).pipe(Effect.flatMap((serverResult) => Effect.all({
+        modelResult: projectModelResult(runtime.name, runtime.modelProjection, serverResult),
+        views: projectViews(runtime.name, runtime.presenters, serverResult),
+    }).pipe(Effect.flatMap(({ modelResult, views }) => encodeToolExecutionModelContext(runtime.name, runtime.modelProjection, modelResult).pipe(Effect.map((modelContext) => ({
+        serverResult,
+        modelResult,
+        views,
+        [toolExecutionModelContext]: modelContext,
+    })))))), Effect.withSpan("popcomputer.structured_chat.tool.execute", {
+        attributes: { tool: runtime.name },
+    }));
+    // SAFETY: command constructors expose a required context while query
+    // constructors expose no context; both feed this operation-tagged runtime.
+    const execute = unsafeCoerce(executeRuntime);
+    const executeCallRuntime = (input, context) => parseCall(input).pipe(Effect.flatMap((call) => executeRuntime(call.arguments, context)));
+    return structuredDefinition("tool")({
+        _tag: "StructuredTool",
+        operation: runtime.operation,
+        name: runtime.name,
+        description: runtime.description,
+        inputSchema: runtime.inputSchema,
+        callSchema,
+        model: {
+            name: runtime.name,
+            description: runtime.description,
+            inputSchema: JSONSchema.make(runtime.inputSchema),
+        },
+        parseCall,
+        execute,
+        executeCall: unsafeCoerce(executeCallRuntime),
+        [toolRuntime]: runtime,
+        pipe() {
+            return Pipeable.pipeArguments(this, arguments);
+        },
+    });
+};
+/** Define one read-only, schema-validated structured chat tool. */
+export const defineTool = (definition) => {
+    Schema.decodeSync(ToolNameSchema)(definition.name);
+    Schema.decodeSync(ToolDescriptionSchema)(definition.description);
+    const name = definition.name;
+    const description = definition.description;
+    const rawCallSchema = Schema.Struct({
+        name: Schema.Literal(name),
+        arguments: definition.input,
+    });
+    // SAFETY: the literal name and input schema are exactly the two ToolCall
+    // fields, and the constituent schemas require no runtime context.
+    const callSchema = unsafeCoerce(rawCallSchema);
+    return makeTool({
+        name,
+        description,
+        inputSchema: definition.input,
+        executeServer: (input) => definition.execute(input),
+        operation: "query",
+        modelProjection: undefined,
+        presenters: [],
+        callSchema,
+    });
+};
+/** Define one side-effecting command requiring a stable idempotency key. */
+export const defineCommand = (definition) => {
+    Schema.decodeSync(ToolNameSchema)(definition.name);
+    Schema.decodeSync(ToolDescriptionSchema)(definition.description);
+    const rawCallSchema = Schema.Struct({
+        name: Schema.Literal(definition.name),
+        arguments: definition.input,
+    });
+    // SAFETY: the literal name and input schema exactly form ToolCall.
+    const callSchema = unsafeCoerce(rawCallSchema);
+    return makeTool({
+        name: definition.name,
+        description: definition.description,
+        inputSchema: definition.input,
+        executeServer: definition.execute,
+        operation: "command",
+        modelProjection: undefined,
+        presenters: [],
+        callSchema,
+    });
+};
+/** Add one bounded model-visible result projection to a tool. */
+const modelResult = (schema, project) => (tool) => {
+    const runtime = tool[toolRuntime];
+    const nextRuntime = {
+        ...runtime,
+        modelProjection: { schema, project },
+    };
+    // SAFETY: this combinator changes only the model-projection slot from
+    // absent to the exact supplied schema and projector.
+    return makeTool(unsafeCoerce(nextRuntime));
+};
+/** Add one optional display-safe view projection to a tool. */
+const present = (view, project) => (tool) => {
+    const runtime = tool[toolRuntime];
+    return makeTool({
+        ...runtime,
+        presenters: [
+            ...runtime.presenters,
+            { view, project },
+        ],
+    });
+};
+/** Combinators that add optional capabilities to a structured tool. */
+export const Tool = {
+    modelResult,
+    present,
+};

package/dist/core/view.d.ts

@@ -0,0 +1,95 @@
+import { Effect, Either, Schema } from "effect";
+import type * as ParseResult from "effect/ParseResult";
+import type { JsonValue } from "./json-value.js";
+/** Stable machine-facing name for one structured chat view. */
+export declare const ViewNameSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Positive protocol version for one structured chat view. */
+export declare const ViewVersionSchema: Schema.filter<Schema.filter<typeof Schema.Number>>;
+/** Minimum runtime shape retained for every structured chat view. */
+export interface ViewDefinitionContract<Name extends string = string, Version extends number = number, InputSchema extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext, DataSchema extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext, PartSchema extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext> {
+    readonly name: Name;
+    readonly version: Version;
+    readonly inputSchema: InputSchema;
+    readonly dataSchema: DataSchema;
+    readonly partSchema: PartSchema;
+    /** Parse unknown application data into one display-safe data part. */
+    readonly parseData: (input: JsonValue) => Effect.Effect<Schema.Schema.Type<PartSchema>, ParseResult.ParseError>;
+    /** Parse an unknown serialized part without requiring an Effect runtime. */
+    readonly decodeEither: (input: JsonValue) => Either.Either<Schema.Schema.Type<PartSchema>, ParseResult.ParseError>;
+}
+/** Parsed data accepted when constructing one view part. */
+export type ViewInput<View extends ViewDefinitionContract> = Schema.Schema.Type<View["inputSchema"]>;
+/** Versioned display data carried by one view part. */
+export type ViewData<View extends ViewDefinitionContract> = Schema.Schema.Type<View["dataSchema"]>;
+/** Complete structured message part produced by one view. */
+export type ViewPart<View extends ViewDefinitionContract> = Schema.Schema.Type<View["partSchema"]>;
+/** One schema-defined, versioned structured chat view. */
+export interface ViewDefinition<Name extends string, Version extends number, InputSchema extends Schema.Schema.AnyNoContext, DataSchema extends Schema.Schema.AnyNoContext, PartSchema extends Schema.Schema.AnyNoContext> extends ViewDefinitionContract<Name, Version, InputSchema, DataSchema, PartSchema> {
+    /** Construct and validate one display-safe data part. */
+    readonly make: (input: Schema.Schema.Type<InputSchema>) => Schema.Schema.Type<PartSchema>;
+    /** Parse unknown input into one display-safe data part. */
+    readonly parseData: (input: JsonValue) => Effect.Effect<Schema.Schema.Type<PartSchema>, ParseResult.ParseError>;
+    /** Parse an unknown serialized part at a runtime boundary. */
+    readonly decode: (input: JsonValue) => Effect.Effect<Schema.Schema.Type<PartSchema>, ParseResult.ParseError>;
+    /** Parse an unknown serialized part without requiring an Effect runtime. */
+    readonly decodeEither: (input: JsonValue) => Either.Either<Schema.Schema.Type<PartSchema>, ParseResult.ParseError>;
+}
+/** Definition input for one versioned structured chat view. */
+export interface DefineViewInput<Name extends string, Version extends number, Fields extends Schema.Struct.Fields> {
+    readonly name: Name;
+    readonly version: Version;
+    readonly schema: Schema.Struct<Fields>;
+}
+type NoContextFields<Fields extends Schema.Struct.Fields> = [
+    Schema.Struct.Context<Fields>
+] extends [never] ? unknown : never;
+/**
+ * Define one typed server-to-browser view contract.
+ *
+ * The package injects `schemaVersion`; application schemas describe display
+ * data only. Every constructor and decoder rejects excess properties.
+ */
+export declare const defineView: <const Name extends string, const Version extends number, Fields extends Schema.Struct.Fields>(definition: DefineViewInput<Name, Version, Fields> & NoContextFields<Fields>) => {
+    name: Name;
+    version: Version;
+    inputSchema: Schema.Struct<Fields>;
+    dataSchema: Schema.Struct<{
+        readonly schemaVersion: Schema.Literal<[Version]>;
+    } & Fields>;
+    partSchema: Schema.Struct<{
+        readonly type: Schema.Literal<["data"]>;
+        readonly name: Schema.Literal<[Name]>;
+        readonly data: Schema.Struct<{
+            readonly schemaVersion: Schema.Literal<[Version]>;
+        } & Fields>;
+    }>;
+    make: (input: Schema.Struct.Type<Fields> extends infer T ? { [K in keyof T]: T[K]; } : never) => {
+        readonly name: Name;
+        readonly type: "data";
+        readonly data: Schema.Struct.Type<{
+            readonly schemaVersion: Schema.Literal<[Version]>;
+        } & Fields> extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never;
+    };
+    parseData: (input: JsonValue) => Effect.Effect<{
+        readonly name: Name;
+        readonly type: "data";
+        readonly data: Schema.Struct.Type<{
+            readonly schemaVersion: Schema.Literal<[Version]>;
+        } & Fields> extends infer T ? { [K in keyof T]: T[K]; } : never;
+    }, ParseResult.ParseError>;
+    decode: (input: JsonValue) => Effect.Effect<{
+        readonly name: Name;
+        readonly type: "data";
+        readonly data: Schema.Struct.Type<{
+            readonly schemaVersion: Schema.Literal<[Version]>;
+        } & Fields> extends infer T ? { [K in keyof T]: T[K]; } : never;
+    }, ParseResult.ParseError, never>;
+    decodeEither: (input: JsonValue) => Either.Either<{
+        readonly name: Name;
+        readonly type: "data";
+        readonly data: Schema.Struct.Type<{
+            readonly schemaVersion: Schema.Literal<[Version]>;
+        } & Fields> extends infer T ? { [K in keyof T]: T[K]; } : never;
+    }, ParseResult.ParseError>;
+};
+export {};

package/dist/core/view.js

@@ -0,0 +1,69 @@
+import { Effect, Either, Schema, unsafeCoerce } from "effect";
+/** Stable machine-facing name for one structured chat view. */
+export const ViewNameSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100), Schema.pattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/));
+/** Positive protocol version for one structured chat view. */
+export const ViewVersionSchema = Schema.Number.pipe(Schema.int(), Schema.between(1, 2_147_483_647));
+/**
+ * Define one typed server-to-browser view contract.
+ *
+ * The package injects `schemaVersion`; application schemas describe display
+ * data only. Every constructor and decoder rejects excess properties.
+ */
+export const defineView = (definition) => {
+    Schema.decodeSync(ViewNameSchema)(definition.name);
+    Schema.decodeSync(ViewVersionSchema)(definition.version);
+    if ("schemaVersion" in definition.schema.fields) {
+        throw new Error("View schemas cannot define the reserved schemaVersion field");
+    }
+    // SAFETY: the reserved schemaVersion field cannot be supplied by Fields;
+    // the literal therefore augments the exact application schema once.
+    const dataSchema = Schema.Struct({
+        schemaVersion: Schema.Literal(definition.version),
+        ...definition.schema.fields,
+    });
+    // SAFETY: these literals and dataSchema exactly describe ViewPart<Name,
+    // Version, Fields>; the assertions retain that generic correlation.
+    const partSchema = Schema.Struct({
+        type: Schema.Literal("data"),
+        name: Schema.Literal(definition.name),
+        data: dataSchema,
+    });
+    // SAFETY: NoContextFields excludes schemas with runtime requirements; this
+    // assertion preserves definition.schema's existing Type and Encoded sides.
+    const runtimeInputSchema = unsafeCoerce(definition.schema);
+    // SAFETY: partSchema was built immediately above from the exact view name,
+    // version, and application fields, with no runtime schema requirements.
+    const runtimePartSchema = unsafeCoerce(partSchema);
+    const decodePart = Schema.decodeUnknown(runtimePartSchema);
+    const decodePartEither = Schema.decodeUnknownEither(runtimePartSchema);
+    const validatePart = Schema.validate(runtimePartSchema);
+    const parseData = (input) => Schema.validate(runtimeInputSchema)(input, {
+        onExcessProperty: "error",
+    }).pipe(Effect.flatMap((data) => validatePart({
+        type: "data",
+        name: definition.name,
+        data: {
+            schemaVersion: definition.version,
+            ...data,
+        },
+    }, { onExcessProperty: "error" })));
+    const make = (input) => Schema.validateSync(runtimePartSchema)({
+        type: "data",
+        name: definition.name,
+        data: {
+            schemaVersion: definition.version,
+            ...input,
+        },
+    }, { onExcessProperty: "error" });
+    return {
+        name: definition.name,
+        version: definition.version,
+        inputSchema: definition.schema,
+        dataSchema,
+        partSchema,
+        make,
+        parseData,
+        decode: (input) => decodePart(input, { onExcessProperty: "error" }),
+        decodeEither: (input) => decodePartEither(input, { onExcessProperty: "error" }),
+    };
+};