@spine-event-engine/ai 0.0.0-stage → 2.0.0-snapshot.24

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# Describe an AI task for an Agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An Agent can ask a model to help with a domain task, such as drafting a reply to a support ticket. This package describes the task: the input and result messages, instructions, and checks the result must pass. It does not choose a provider or store credentials. The package is currently an experimental snapshot.
+
+## Install
+
+Install it with the Protobuf package and your generated application messages:
+
+```sh
+pnpm add @spine-event-engine/ai@snapshot @spine-event-engine/proto@snapshot @bufbuild/protobuf
+```
+
+## Define the task
+
+The support example accepts a `DraftSupportReply` Command containing the ticket facts and expects a typed `SupportReply`. These descriptors come from the application's domain Protos.
+
+<!-- prettier-ignore-start -->
+
+<!-- docs-snippet-path: examples/support/src/model.ts -->
+
+```ts
+import { AiModel } from "@spine-event-engine/ai";
+import { DraftSupportReplySchema } from "../generated/spine/examples/support/commands_pb.js";
+import { SupportReplySchema } from "../generated/spine/examples/support/types_pb.js";
+
+const draftSupportReply = AiModel.define({
+    name: "draft-support-reply",
+    version: "1",
+    kind: "generation",
+    input: DraftSupportReplySchema,
+    output: SupportReplySchema,
+    outputMode: "prompt-and-validate",
+    instructions: "Draft a reply for a support person to review using the supplied ticket facts.",
+});
+```
+
+<!-- prettier-ignore-end -->
+
+`prompt-and-validate` asks the provider for a result and checks the parsed message locally. A provider that supports native schema output can use `native-schema` instead; local output validation still applies. The [support application](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/README.md) adds a domain rule so a blank reply cannot become a proposal. Defining a task does not make a model request.
+
+## Connect a deployment
+
+The task above says what input and output mean. A deployment says which permitted provider account and model will do that task. The [adapter guide](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/ai-vercel-ax/README.md) returns a registration with a model reference, credential setup, and authorization check. Build an `AiRegistry` outside the Agent and attach it to the Bounded Context:
+
+<!-- prettier-ignore-start -->
+
+<!-- docs-snippet-path: examples/support/test/support-blackbox.test.ts -->
+
+```ts
+import {
+    AiRegistry,
+    type AiBackendRegistration,
+} from "@spine-event-engine/ai";
+
+/**
+ * Selects a registered provider model for generation tasks.
+ *
+ * @param registration Deployment configured by the trusted application.
+ * @returns Registry to install while building the Bounded Context.
+ */
+function generationRegistry(registration: AiBackendRegistration): AiRegistry {
+    return AiRegistry.create({
+        defaultModels: { generation: registration.ref },
+    }).register(registration);
+}
+```
+
+<!-- prettier-ignore-end -->
+
+The [support context factory](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/src/index.ts) calls `withAi(registry)` when it builds its Agent repository. The [support walkthrough](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/README.md#3-invoke-the-task-from-the-agent) shows the actual handler calling `this.ai.invoke(draftSupportReply, { call, conversation, input })` and turning its result into a domain Event. The [BlackBox step](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/README.md#4-configure-and-test-the-full-flow) shows the same path with a controlled test deployment. The handler does not need a provider SDK or credential.
+
+An Agent task can also allow named tools. **MCP** is a protocol that lets a model ask the application to run one of those tools and return its result. The application explicitly lists permitted tools and checks access before a tool runs; model text alone grants no permission. [Release Notes Studio](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/release-notes/README.md#6-let-the-model-ask-for-git-details) uses read-only Git tools to supply evidence for a draft.
+
+For exact definition fields, deployment selection, optional application limits, tool registration, and result types, see the [coding-agent reference](REFERENCE.md).

package/REFERENCE.md

@@ -0,0 +1,238 @@
+# Agent AI facade reference
+
+Audience: coding agents implementing or checking the AI facade and deployment contracts.
+
+## Typed operations and deployments
+
+`AiModel.define()` describes one application operation. It validates and copies
+its definition synchronously; defining it does not call a provider. Input and
+output are generated Protobuf descriptors. The definition includes a name,
+version, and either generation instructions or decision questions. Applications
+may configure ceilings for an operation; omitted values impose no such ceiling.
+Register the resulting object among the Agent repository's `ai.models`.
+
+A `ModelRef` identifies a configured deployment by name and revision.
+`ModelRef.of()` creates that Protobuf value. Deployment registrations provide an
+adapter, authenticated connection callbacks, and a credential-free account,
+endpoint and model identity. They are separate from the application operation:
+the same drafting operation can use a different permitted deployment without
+putting provider SDK calls in its Entity handler.
+
+`AiRegistry.create()` validates deployment defaults and any configured invocation,
+concurrency or queue ceilings. Register deployments with `register()` and configured MCP servers with
+`registerTools()`. Defaults, limits and tool policy freeze when the runtime
+binds the registry. `register()` can append a unique deployment afterward;
+existing references and policy cannot be replaced.
+Choose a generation default, a decision default, or both. A capability's kind
+must match its selected deployment. The server package supplies Bounded Context and
+repository integration; this package alone does not start a signal handler.
+
+## Calls and results
+
+Inside a signal handler, `this.ai.invoke(model, { call, conversation, input })`
+returns a `Promise<AiResult<Output>>`. `call` names the logical operation within
+that accepted signal, and `conversation` is an explicit `ConversationId`.
+`input` must be an instance of the declared input message. On success, inspect
+`value` and emit the application's domain outcome. On operational failure,
+inspect `failure.code`, `retryableByNewSignal`, and `diagnosticId`. Both results
+carry the operation ID. A technical handler defect can still fail the handler;
+`AiResult` is not a catch-all for arbitrary application exceptions.
+
+The runtime saves the named operation, prepared requests and received results.
+Recovery reuses recorded results and rejects changed input or configuration for
+an existing call. A fresh accepted signal can make a new model request and may
+receive different words. The framework does not promise repeatable fresh model
+output or know whether every model assertion is true.
+
+`this.ai.select(kind, model)` records an instance preference for later signals.
+Pass `undefined` to restore inheritance. The current signal keeps its selected
+deployment. The repository's allowed model list remains an authorization boundary;
+an instance preference cannot bypass it. See the
+[server reference](../server/REFERENCE.md) for configuration precedence and
+execution lifecycle.
+
+## Generation validation and corrections
+
+Generation explicitly chooses `native-schema` or `prompt-and-validate`.
+Native schema mode requires a supported descriptor and provider profile; it does
+not silently fall back to text prompting. Prompt-and-validate mode supplies the
+model-facing representation and checks the resulting text locally.
+
+Both paths parse and validate the model response against the declared output message.
+A versioned `validation.check(value, input)` then applies a pure application rule.
+Return concrete issues with a code, field path, and safe message. A field path can
+be empty for an issue affecting the whole result. The callback receives the same
+input facts as the operation; it must not fetch new data or perform side effects.
+
+A response that fails validation may lead to a corrective request, subject to any
+configured request, time and byte ceilings. The correction includes the actual detected issues, and the
+runtime retains that request as another attempt. It cannot describe an alleged
+hallucination that no validation rule detected. Refusal, cancellation, exhausted
+configured limits and unknown external write outcomes have explicit failure paths.
+
+Native output schemas support a conservative descriptor subset. Unsupported
+fields or options produce field-specific errors before dispatch. See the
+[adapter reference](../ai-vercel-ax/REFERENCE.md) for supported provider profiles.
+
+## Non-generative decisions
+
+A decision capability defines boolean, choice, or score questions. The adapter
+validates question IDs, answer kinds and ranges before calling the versioned
+`mapping.toMessage(result, input)`. That pure callback creates the output Proto;
+Proto validation and the application validation rule still apply. Optional
+requirements for full probability distributions and independent question
+execution must be supported by the deployment. See the
+[Jev registration example](../ai-vercel-ax/REFERENCE.md#openrouter-jev-decision-registration).
+
+## Limits and tools
+
+Applications may set ceilings for physical model requests, tool calls, elapsed
+time, input bytes, output bytes and generation tokens. Each setting is optional.
+Registry invocation settings may additionally limit work shared by all selected
+handlers of one signal, including recorded reads. Omitting a setting does not
+substitute a framework default. Cancellation remains available without a deadline.
+
+Recovery retains measured usage and any configured deadline. Completed exchanges
+record their received byte counts. When a configured shared output ceiling applies,
+the runtime reserves the remaining allowance before dispatch; if a response ends
+without a complete byte count, that reservation remains charged. Without an output
+ceiling, the runtime still records dispatch and measured bytes.
+
+Set `maxOutputTokens` only when the deployment can enforce it. An adapter that
+cannot enforce an explicit token ceiling rejects the call before inference. Byte
+ceilings apply to materialized and received data, including protocol framing;
+they are different from model token counts.
+
+Await each model call before starting the next one in the same handler. Concurrent
+calls, an unfinished call when the handler returns, and reuse of a facade after
+its handler finishes are programming errors.
+
+Bounded Contexts that share one `AiRegistry` object also share any configured
+execution capacity within that process. `concurrentOperations` can limit active
+Agent executions; `queuedOperations` can limit additional work waiting in memory
+for a slot. Both settings are optional. If capacity is configured and full, further
+accepted signals remain in durable storage until a slot becomes available. Waiting
+before execution does not consume a configured execution deadline. Recovery keeps
+the deadline of an execution that already started. Separate registries and
+processes do not share these settings.
+
+`Mcp.server()` validates an explicitly configured tool server. A generation
+capability lists the server/tool references it may use. Connection and per-call
+authorization receive the accepted actor, tenant and Agent scope. The runtime
+records tool intent before dispatch and retains results before model continuation.
+Per-tool timeouts and argument/result byte ceilings are optional; no values are
+substituted when they are omitted.
+A write whose result is unknown cannot be sent again automatically. Supported
+content and protocol limits are documented by the optional adapter; model text
+cannot add a server, change credentials, or extend a tool's permission.
+
+## Configure an MCP lookup
+
+This example adds a locally running knowledge service to support drafting. Its
+`lookup` tool is read-only and requires no credentials in this demonstration.
+The server must expose that exact tool name. Only the configured tool is made
+available to this capability. The model may request it; permission does not
+force a call.
+
+The generated message imports come from the [Support example](../../examples/support/README.md).
+Supply a generation deployment created with `VercelAx.model()` as shown in the
+[adapter quickstart](../ai-vercel-ax/README.md). Register `knowledgeDraft` among
+the Agent repository's `ai.models`, then invoke that capability from its handler.
+
+<!-- prettier-ignore-start -->
+
+<!-- docs-snippet-path: examples/support/src/index.ts -->
+
+```ts
+import { AiModel, AiRegistry, Mcp, type AiBackendRegistration } from "@spine-event-engine/ai";
+import { DraftSupportReplySchema } from "../generated/spine/examples/support/commands_pb.js";
+import { SupportReplySchema } from "../generated/spine/examples/support/types_pb.js";
+
+/** Drafts a reply using supplied facts and the permitted knowledge lookup. */
+const knowledgeDraft = AiModel.define({
+    name: "knowledge-support-reply",
+    version: "1",
+    kind: "generation",
+    input: DraftSupportReplySchema,
+    output: SupportReplySchema,
+    outputMode: "prompt-and-validate",
+    instructions:
+        "Use the reported facts and relevant knowledge articles to draft a reply for human review.",
+    tools: [{ server: "knowledge", tool: "lookup" }],
+});
+
+/** Permits only lookup on the public demonstration knowledge service. */
+const knowledge = Mcp.server({
+    id: "knowledge",
+    revision: "1",
+    transport: { kind: "streamable-http", url: "http://127.0.0.1:3333/mcp" },
+    authorizeConnect: () => true,
+    tools: {
+        lookup: {
+            effect: "read",
+            authorize: () => true,
+        },
+    },
+});
+
+/**
+ * Registers a local public knowledge lookup and a configured generation model.
+ *
+ * @param deployment Authenticated model registration created by the application.
+ * @returns Registry for BoundedContextBuilder.withAi().
+ */
+function supportAi(deployment: AiBackendRegistration): AiRegistry {
+    return AiRegistry.create({
+        defaultModels: { generation: deployment.ref },
+    })
+        .register(deployment)
+        .registerTools(knowledge);
+}
+```
+
+<!-- prettier-ignore-end -->
+
+The `true` callbacks permit access to this public demonstration service. For a
+restricted service, `authorizeConnect(scope, control)` checks connection access;
+`tools.lookup.authorize(scope, call, control)` checks each proposed call and its
+arguments. `scope` includes the accepted actor and tenant. Supply credentials with
+`transport.headers(scope, control)` for HTTP, or `transport.environment(scope,
+control)` for a configured stdio process. Resolve secrets in these callbacks;
+do not put them in model input or recorded identity.
+
+No MCP client or transport is created in Entity code. The selected Vercel adapter
+supplies it when the operation runs. Setup traffic and tool responses contribute
+to the invocation's measured byte counts. If you configure a byte ceiling, include discovery
+as well as model output.
+See the [adapter transport limits](../ai-vercel-ax/REFERENCE.md) for supported
+schemas, result content and HTTP/stdio behavior, and the
+[full Agent/MCP test](../server-blackbox-tests/test/agent-vercel-mcp-blackbox.test.ts)
+for an executable local protocol example.
+
+## History and testing
+
+Agent history is retained by its repository. `fullHistory()` returns
+`AgentHistoryEntry` messages whose oneof contains a conversation record, System
+Event, or emitted domain Event. The other methods read a single category:
+`conversationHistory()` requires a conversation ID, `systemEventHistory()` reads
+System Events, and `domainEventHistory()` reads emitted domain Events.
+
+All four take a positive `pageSize` and an optional opaque `cursor`, return newest
+entries first, and provide `nextCursor` for older records. There is no 100-record
+retention limit. A cursor belongs to its Agent, tenant, repository, category and
+conversation.
+Recording is mandatory and continues through logical Entity deletion or archive.
+
+`AiTestBackend` scripts deployment responses while `BlackBox` remains the test
+entrance for Commands, Events, state and audit. See the
+[Support example](../../examples/support/README.md) and
+[testing reference](../testing/REFERENCE.md).
+
+## Adapter boundary
+
+Entity code uses the public SDK-free facade. Adapter authors use the separate
+`spi/adapter` entry point. Server integration uses the internal runtime SPI;
+application code must not call those controls to bypass signal handling.
+Unknown usage stays absent in `AiUsage`; a reported zero has an explicit
+`AiTokenCount` message. Credentials belong in application connection callbacks
+and are not part of recorded model identity or diagnostic messages.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { MessageSchema } from "@spine-event-engine/core";
+import type { ModelRef as ProtoModelRef } from "@spine-event-engine/proto/agent";
+import { AiModel as AiModelFactory, ModelRef as ModelRefFactory } from "./internal/model.js";
+import type { AiModel as InternalAiModel } from "./internal/model.js";
+/**
+ * SDK-free typed capability created only by {@link AiModel.define}.
+ *
+ * @typeParam I - Input message descriptor.
+ * @typeParam O - Output message descriptor.
+ */
+export type AiModel<I extends MessageSchema, O extends MessageSchema> = InternalAiModel<I, O>;
+/**
+ * Creates validated typed capabilities.
+ */
+export declare const AiModel: typeof AiModelFactory;
+/**
+ * Credential-free Protobuf deployment reference.
+ */
+export type ModelRef = ProtoModelRef;
+/**
+ * Constructs canonical deployment references.
+ */
+export declare const ModelRef: typeof ModelRefFactory;
+export { AiRegistry } from "./internal/registry.js";
+export { Mcp } from "./internal/mcp.js";
+export type { AiBackendRegistration } from "./internal/registration.js";
+export type { McpServerRegistration } from "./internal/mcp.js";
+export type { AgentAi, AiAnswer, AiConnectionIdentity, AiControl, AiDecisionResult, AiDefaultModels, AiFailure, AiInvocationLimits, AiJson, AiLimits, AiModelBase, AiModelDefinition, AiQuestion, AiRegistryOptions, AiResult, AiScope, AiToolCall, AiToolRef, AiValidationIssue, ConversationHistoryRead, HistoryPage, HistoryRead, McpServerDefinition, McpToolPolicy, McpTransport, } from "./internal/contracts.js";
+export type { ModelName, ModelRevision, ModelPreference, AiCapabilityName, AiCapabilityRevision, AiValidationRevision, AiMappingRevision, AiDiagnosticId, McpServerId, McpToolName, AiModelRequestLimit, AiToolCallLimit, AiDeadlineMillis, AiInputByteLimit, AiOutputByteLimit, AiOutputTokenLimit, AiTokenCount, AiProviderName, AiAccountIdentity, AiEndpointIdentity, AiProviderModelName, AiOperationLimits, AiUsage, DecisionQuestionId, DecisionAlternativeKey, ConversationRecordId, AgentHistoryCursor, AgentHistoryEntry, AgentOperationRef, AgentAiOperationStarted, AgentModelAttemptStarted, AgentModelAttemptFinished, AgentAiResultAdmitted, AgentAiOperationFailed, AgentToolCallStarted, AgentToolCallFinished, AgentModelSelectionChanged, AgentInvocationTerminated, AiAttemptId, AiContentDigest, AiOperationId, AiToolCallId, ConversationId, ConversationRecord, GenerationRequest, GenerationResponse, ModelToolCall, DecisionRequest, DecisionResponse, ToolRequest, ToolResponse, DecisionQuestion, DecisionAnswer, DecisionDistribution, DecisionRounding, DecisionChoice, DecisionProbability, } from "@spine-event-engine/proto/agent";
+export { ModelNameSchema, ModelRevisionSchema, ModelPreferenceSchema, AiCapabilityNameSchema, AiCapabilityRevisionSchema, AiValidationRevisionSchema, AiMappingRevisionSchema, AiDiagnosticIdSchema, McpServerIdSchema, McpToolNameSchema, AiModelRequestLimitSchema, AiToolCallLimitSchema, AiDeadlineMillisSchema, AiInputByteLimitSchema, AiOutputByteLimitSchema, AiOutputTokenLimitSchema, AiTokenCountSchema, AiProviderNameSchema, AiAccountIdentitySchema, AiEndpointIdentitySchema, AiProviderModelNameSchema, AiOperationLimitsSchema, AiUsageSchema, AiConnectionIdentitySchema, DecisionQuestionIdSchema, DecisionAlternativeKeySchema, ConversationRecordIdSchema, AgentHistoryCursorSchema, AgentHistoryEntrySchema, AgentOperationRefSchema, AgentAiOperationStartedSchema, AgentModelAttemptStartedSchema, AgentModelAttemptFinishedSchema, AgentAiResultAdmittedSchema, AgentAiOperationFailedSchema, AgentToolCallStartedSchema, AgentToolCallFinishedSchema, AgentModelSelectionChangedSchema, AgentInvocationTerminatedSchema, AiAttemptIdSchema, AiContentDigestSchema, AiModelKind, AiOperationIdSchema, AiToolCallIdSchema, ConversationIdSchema, ConversationRecordSchema, ModelRefSchema, GenerationRequestSchema, GenerationResponseSchema, ModelToolCallSchema, DecisionRequestSchema, DecisionResponseSchema, ToolRequestSchema, ToolResponseSchema, DecisionQuestionSchema, DecisionAnswerSchema, DecisionDistributionSchema, DecisionRoundingSchema, DecisionChoiceSchema, DecisionProbabilitySchema, DecisionQuestionKind, ToolEffect, AiOutcome, AiFailureCode, AiExecutionMode, } from "@spine-event-engine/proto/agent";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,KAAK,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,aAAa,IAAI,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE9F;;GAEG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,cAA+B,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,eAAiC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AACxC,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EACV,OAAO,EACP,QAAQ,EACR,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,MAAM,EACN,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,OAAO,EACP,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,YAAY,GACb,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,SAAS,EACT,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,WAAW,EACX,eAAe,EACf,aAAa,EACb,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,aAAa,EACb,0BAA0B,EAC1B,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,8BAA8B,EAC9B,+BAA+B,EAC/B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,+BAA+B,EAC/B,iBAAiB,EACjB,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,GAChB,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { AiModel as AiModelFactory, ModelRef as ModelRefFactory } from "./internal/model.js";
+/**
+ * Creates validated typed capabilities.
+ */
+export const AiModel = AiModelFactory;
+/**
+ * Constructs canonical deployment references.
+ */
+export const ModelRef = ModelRefFactory;
+export { AiRegistry } from "./internal/registry.js";
+export { Mcp } from "./internal/mcp.js";
+export { ModelNameSchema, ModelRevisionSchema, ModelPreferenceSchema, AiCapabilityNameSchema, AiCapabilityRevisionSchema, AiValidationRevisionSchema, AiMappingRevisionSchema, AiDiagnosticIdSchema, McpServerIdSchema, McpToolNameSchema, AiModelRequestLimitSchema, AiToolCallLimitSchema, AiDeadlineMillisSchema, AiInputByteLimitSchema, AiOutputByteLimitSchema, AiOutputTokenLimitSchema, AiTokenCountSchema, AiProviderNameSchema, AiAccountIdentitySchema, AiEndpointIdentitySchema, AiProviderModelNameSchema, AiOperationLimitsSchema, AiUsageSchema, AiConnectionIdentitySchema, DecisionQuestionIdSchema, DecisionAlternativeKeySchema, ConversationRecordIdSchema, AgentHistoryCursorSchema, AgentHistoryEntrySchema, AgentOperationRefSchema, AgentAiOperationStartedSchema, AgentModelAttemptStartedSchema, AgentModelAttemptFinishedSchema, AgentAiResultAdmittedSchema, AgentAiOperationFailedSchema, AgentToolCallStartedSchema, AgentToolCallFinishedSchema, AgentModelSelectionChangedSchema, AgentInvocationTerminatedSchema, AiAttemptIdSchema, AiContentDigestSchema, AiModelKind, AiOperationIdSchema, AiToolCallIdSchema, ConversationIdSchema, ConversationRecordSchema, ModelRefSchema, GenerationRequestSchema, GenerationResponseSchema, ModelToolCallSchema, DecisionRequestSchema, DecisionResponseSchema, ToolRequestSchema, ToolResponseSchema, DecisionQuestionSchema, DecisionAnswerSchema, DecisionDistributionSchema, DecisionRoundingSchema, DecisionChoiceSchema, DecisionProbabilitySchema, DecisionQuestionKind, ToolEffect, AiOutcome, AiFailureCode, AiExecutionMode, } from "@spine-event-engine/proto/agent";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAW7F;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAA0B,cAAc,CAAC;AAO7D;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA2B,eAAe,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAyFxC,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,aAAa,EACb,0BAA0B,EAC1B,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,8BAA8B,EAC9B,+BAA+B,EAC/B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,+BAA+B,EAC/B,iBAAiB,EACjB,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,GAChB,MAAM,iCAAiC,CAAC"}