@voltro/ai 0.1.0

package/dist/agent.d.ts

@@ -0,0 +1,101 @@
+import { ActionProcedureDescriptor } from '@voltro/protocol';
+import { QueryProcedureDescriptor } from '@voltro/protocol';
+import { Schema } from 'effect';
+
+declare const AGENT_DESCRIPTOR_BRAND: "@voltro/ai/AgentDescriptor";
+
+declare const AGENT_DESCRIPTOR_SYMBOL: unique symbol;
+
+export declare interface AgentDescriptor<S extends Schema.Schema.Any = DefaultAgentInputSchema> {
+    readonly [AGENT_DESCRIPTOR_SYMBOL]: true;
+    readonly _brand: typeof AGENT_DESCRIPTOR_BRAND;
+    /** Wire id → rpc tags `<name>.send` / `<name>.messages`. */
+    readonly name: string;
+    /** Input schema (default `{ prompt: string }`). The send route's wire input
+     *  extends this with `{ threadId, order }`. */
+    readonly input?: S;
+}
+
+/** The decoded input an agent's executor sees, derived from its schema. */
+export declare type AgentInput<S extends Schema.Schema.Any> = Schema.Schema.Type<S>;
+
+/** The agent's input schema (default `{ prompt: string }`). */
+export declare const agentInputSchema: (desc: AnyAgentDescriptor) => Schema.Schema.Any;
+
+export declare const agentMessageSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    threadId: typeof Schema.String;
+    role: typeof Schema.String;
+    content: typeof Schema.String;
+    streaming: typeof Schema.Boolean;
+    order: typeof Schema.Number;
+    stepOrder: typeof Schema.Number;
+    parts: Schema.Array$<Schema.TypeLiteral<{
+        type: typeof Schema.String;
+    }, readonly [{
+        readonly key: typeof Schema.String;
+        readonly value: typeof Schema.Unknown;
+    }]>>;
+}>;
+
+/**
+ * The two browser-safe route descriptors synthesized for an agent. The SAME
+ * source the runtime synthesis (`agentSynthesis.ts`) and codegen both consume,
+ * so "what the server serves" and "what the client is typed for" can't drift.
+ */
+export declare const agentRouteDescriptors: (desc: AnyAgentDescriptor) => {
+    send: ActionProcedureDescriptor<`${string}.send`, Schema.Schema.Any, Schema.Struct<{
+        text: typeof Schema.String;
+    }>, typeof Schema.Never>;
+    messages: QueryProcedureDescriptor<`${string}.messages`, Schema.Struct<{
+        threadId: typeof Schema.String;
+    }>, Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        threadId: typeof Schema.String;
+        role: typeof Schema.String;
+        content: typeof Schema.String;
+        streaming: typeof Schema.Boolean;
+        order: typeof Schema.Number;
+        stepOrder: typeof Schema.Number;
+        parts: Schema.Array$<Schema.TypeLiteral<{
+            type: typeof Schema.String;
+        }, readonly [{
+            readonly key: typeof Schema.String;
+            readonly value: typeof Schema.Unknown;
+        }]>>;
+    }>>, typeof Schema.Never>;
+};
+
+/** A descriptor of any input shape — for the type-erased runtime helpers. */
+export declare type AnyAgentDescriptor = AgentDescriptor<Schema.Schema.Any>;
+
+declare const DEFAULT_INPUT: Schema.Struct<{
+    prompt: typeof Schema.String;
+}>;
+
+/** Default input schema type when `input` is omitted (`{ prompt: string }`). */
+export declare type DefaultAgentInputSchema = typeof DEFAULT_INPUT;
+
+/**
+ * Declare an agent's browser-safe wire contract: its `name` and `input`
+ * schema. The decoded input type is inferred from the schema (like
+ * `defineQuery`). Behaviour (system prompt, tools, model + key, maxSteps) lives
+ * in the paired `*.agent.server.tsx` via `defineAgentExecutor`.
+ *
+ * ```ts
+ * // support.agent.tsx (browser-safe descriptor)
+ * export const support = defineAgent({
+ *   name: 'support',
+ *   input: Schema.Struct({ prompt: Schema.String, locale: Schema.optional(Schema.String) }),
+ * })
+ * ```
+ */
+export declare const defineAgent: <S extends Schema.Schema.Any = DefaultAgentInputSchema>(config: {
+    readonly name: string;
+    readonly input?: S;
+}) => AgentDescriptor<S>;
+
+/** Discovery predicate for `*.agent.tsx` exports. */
+export declare const isAgentDescriptor: (x: unknown) => x is AnyAgentDescriptor;
+
+export { }

package/dist/agent.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, r, t as i } from "./agentDescriptor-DCd4F9zj.js";
+export { i as agentInputSchema, n as agentMessageSchema, r as agentRouteDescriptors, t as defineAgent, e as isAgentDescriptor };

package/dist/agentDescriptor-DCd4F9zj.js

@@ -0,0 +1,45 @@
+import { Schema as e } from "effect";
+import { defineAction as t, defineQuery as n } from "@voltro/protocol";
+//#region src/agentConstants.ts
+var r = "agent_threads", i = "agent_messages", a = e.Struct({ prompt: e.String }), o = "@voltro/ai/AgentDescriptor", s = Symbol.for("@voltro/ai/AgentDescriptor"), c = (e) => ({
+	[s]: !0,
+	_brand: o,
+	name: e.name,
+	...e.input === void 0 ? {} : { input: e.input }
+}), l = (e) => typeof e == "object" && !!e && e._brand === o, u = (e) => e.input ?? a, d = e.Struct({ type: e.String }, {
+	key: e.String,
+	value: e.Unknown
+}), f = e.Struct({
+	id: e.String,
+	threadId: e.String,
+	role: e.String,
+	content: e.String,
+	streaming: e.Boolean,
+	order: e.Number,
+	stepOrder: e.Number,
+	parts: e.Array(d)
+}), p = (t) => {
+	let n = u(t), r = e.Struct({
+		threadId: e.String,
+		order: e.Number
+	});
+	try {
+		return e.extend(n, r);
+	} catch {
+		return r;
+	}
+}, m = (r) => ({
+	send: t({
+		name: `${r.name}.send`,
+		input: p(r),
+		output: e.Struct({ text: e.String })
+	}),
+	messages: n({
+		name: `${r.name}.messages`,
+		input: e.Struct({ threadId: e.String }),
+		output: e.Array(f),
+		source: i
+	})
+});
+//#endregion
+export { l as a, c as i, f as n, i as o, m as r, r as s, u as t };

package/dist/events.d.ts

@@ -0,0 +1,122 @@
+import { Schema } from 'effect';
+
+/** Error taxonomy. `retryable` on the event drives client/agent retry. */
+export declare const AgentErrorCode: Schema.Literal<["provider", "tool", "timeout", "cancelled", "decode", "internal"]>;
+
+export declare type AgentErrorCode = typeof AgentErrorCode.Type;
+
+export declare const AgentEvent: Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["token"]>;
+    text: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["reasoning"]>;
+    text: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["toolCall"]>;
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    input: typeof Schema.Unknown;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["toolResult"]>;
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    output: Schema.optional<typeof Schema.Unknown>;
+    error: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["source"]>;
+    sourceType: Schema.Literal<["url", "document"]>;
+    id: typeof Schema.String;
+    url: Schema.optional<typeof Schema.String>;
+    title: Schema.optional<typeof Schema.String>;
+    mediaType: Schema.optional<typeof Schema.String>;
+    filename: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["file"]>;
+    mediaType: typeof Schema.String;
+    data: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["message"]>;
+    role: typeof Schema.String;
+    content: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["error"]>;
+    code: Schema.Literal<["provider", "tool", "timeout", "cancelled", "decode", "internal"]>;
+    message: typeof Schema.String;
+    retryable: typeof Schema.Boolean;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["done"]>;
+    finishReason: typeof Schema.String;
+    usage: Schema.Struct<{
+        inputTokens: Schema.optional<typeof Schema.Number>;
+        outputTokens: Schema.optional<typeof Schema.Number>;
+        totalTokens: Schema.optional<typeof Schema.Number>;
+    }>;
+}>]>;
+
+export declare type AgentEvent = typeof AgentEvent.Type;
+
+/**
+ * One persisted event of a RESUMABLE stream: an `AgentEvent` plus its monotonic
+ * 1-based position. `seq` is the resume cursor — a client that has rendered up
+ * to `seq=N` reconnects with `fromSeq: N` and gets `N+1…` replayed, then live.
+ *
+ * This is the WIRE element for a resumable `defineStream` (`element: SeqEvent`).
+ * It lives here — next to `AgentEvent`, with ZERO server imports — so a
+ * browser-loaded stream descriptor can reference the Schema without dragging
+ * the server-only resumable-stream store graph (`@voltro/database`) into the
+ * client bundle.
+ */
+export declare const SeqEvent: Schema.Struct<{
+    seq: typeof Schema.Number;
+    event: Schema.Union<[Schema.Struct<{
+        _tag: Schema.Literal<["token"]>;
+        text: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["reasoning"]>;
+        text: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["toolCall"]>;
+        id: typeof Schema.String;
+        name: typeof Schema.String;
+        input: typeof Schema.Unknown;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["toolResult"]>;
+        id: typeof Schema.String;
+        name: typeof Schema.String;
+        output: Schema.optional<typeof Schema.Unknown>;
+        error: Schema.optional<typeof Schema.String>;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["source"]>;
+        sourceType: Schema.Literal<["url", "document"]>;
+        id: typeof Schema.String;
+        url: Schema.optional<typeof Schema.String>;
+        title: Schema.optional<typeof Schema.String>;
+        mediaType: Schema.optional<typeof Schema.String>;
+        filename: Schema.optional<typeof Schema.String>;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["file"]>;
+        mediaType: typeof Schema.String;
+        data: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["message"]>;
+        role: typeof Schema.String;
+        content: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["error"]>;
+        code: Schema.Literal<["provider", "tool", "timeout", "cancelled", "decode", "internal"]>;
+        message: typeof Schema.String;
+        retryable: typeof Schema.Boolean;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["done"]>;
+        finishReason: typeof Schema.String;
+        usage: Schema.Struct<{
+            inputTokens: Schema.optional<typeof Schema.Number>;
+            outputTokens: Schema.optional<typeof Schema.Number>;
+            totalTokens: Schema.optional<typeof Schema.Number>;
+        }>;
+    }>]>;
+}>;
+
+export declare type SeqEvent = typeof SeqEvent.Type;
+
+export { }

package/dist/events.js

@@ -0,0 +1,54 @@
+import { Schema as e } from "effect";
+//#region src/agentEvent.ts
+var t = e.Literal("provider", "tool", "timeout", "cancelled", "decode", "internal"), n = e.Struct({
+	inputTokens: e.optional(e.Number),
+	outputTokens: e.optional(e.Number),
+	totalTokens: e.optional(e.Number)
+}), r = e.Union(e.Struct({
+	_tag: e.Literal("token"),
+	text: e.String
+}), e.Struct({
+	_tag: e.Literal("reasoning"),
+	text: e.String
+}), e.Struct({
+	_tag: e.Literal("toolCall"),
+	id: e.String,
+	name: e.String,
+	input: e.Unknown
+}), e.Struct({
+	_tag: e.Literal("toolResult"),
+	id: e.String,
+	name: e.String,
+	output: e.optional(e.Unknown),
+	error: e.optional(e.String)
+}), e.Struct({
+	_tag: e.Literal("source"),
+	sourceType: e.Literal("url", "document"),
+	id: e.String,
+	url: e.optional(e.String),
+	title: e.optional(e.String),
+	mediaType: e.optional(e.String),
+	filename: e.optional(e.String)
+}), e.Struct({
+	_tag: e.Literal("file"),
+	mediaType: e.String,
+	data: e.String
+}), e.Struct({
+	_tag: e.Literal("message"),
+	role: e.String,
+	content: e.String
+}), e.Struct({
+	_tag: e.Literal("error"),
+	code: t,
+	message: e.String,
+	retryable: e.Boolean
+}), e.Struct({
+	_tag: e.Literal("done"),
+	finishReason: e.String,
+	usage: n
+})), i = e.Struct({
+	seq: e.Number,
+	event: r
+});
+//#endregion
+export { t as AgentErrorCode, r as AgentEvent, i as SeqEvent };