@forgeax/engine-tool-runtime 0.1.29 → 0.1.31

package/dist/api.d.ts

@@ -0,0 +1,72 @@
+import type { ToolCallerIdentity, ToolContribution, ToolDescriptor, ToolExecutionOwner, ToolRealm, ToolRun, ToolRunOptions } from './types.js';
+export type ToolApiProviderState = 'pending' | 'active' | 'revoking' | 'revoked' | 'failed';
+export interface ToolApiProviderInput {
+    /** Stable provider identity within one source. */
+    readonly providerId: string;
+    /** Host/source identity. Different sources may expose the same operation id. */
+    readonly sourceId: string;
+    readonly realm: ToolRealm;
+    readonly generation?: number;
+    readonly fiberId?: string | number;
+    readonly module?: string;
+    readonly fiberState?: string;
+    /** Async plugin activation stays non-callable until explicitly activated. */
+    readonly initialState?: 'pending' | 'active';
+    readonly tools: readonly ToolContribution[];
+    /** Domain authorization remains owned by the provider. */
+    readonly authorize?: (caller: ToolCallerIdentity | undefined, operation: ToolDescriptor) => boolean;
+}
+export interface ToolApiProviderSnapshot {
+    readonly owner: ToolExecutionOwner;
+    readonly state: ToolApiProviderState;
+    readonly fiberState?: string;
+    readonly callable: boolean;
+    readonly operationIds: readonly string[];
+}
+export interface ToolApiRecord {
+    readonly descriptor: ToolDescriptor;
+    readonly owner: ToolExecutionOwner;
+    readonly providerState: ToolApiProviderState;
+    readonly declared: true;
+    readonly callable: boolean;
+    readonly fiberState?: string;
+}
+export interface ToolApiSnapshot {
+    readonly providers: readonly ToolApiProviderSnapshot[];
+    readonly operations: readonly ToolApiRecord[];
+}
+export interface ToolApiProviderHandle {
+    readonly owner: ToolExecutionOwner;
+    readonly snapshot: () => ToolApiProviderSnapshot;
+    /** Mark a pending provider callable after its domain apply succeeds. */
+    readonly activate: (fiberState?: string) => void;
+    /** Mark a pending/active provider failed without making it callable. */
+    readonly fail: (reason?: string, fiberState?: string) => void;
+    /** Withdraw admission and wait for every executor to actually exit. */
+    readonly revoke: (reason?: string) => Promise<void>;
+}
+export interface ToolApiRunOptions extends Omit<ToolRunOptions, 'owner'> {
+    /** Explicit provider route. Required when multiple sources expose an id. */
+    readonly providerId?: string;
+    readonly sourceId?: string;
+    /** Provider generation observed by the caller. */
+    readonly generation?: number;
+}
+export interface ToolApi {
+    readonly snapshot: () => ToolApiSnapshot;
+    readonly list: () => readonly ToolApiRecord[];
+    readonly describe: (id: string, sourceId?: string) => readonly ToolApiRecord[];
+    readonly registerProvider: (input: ToolApiProviderInput) => ToolApiProviderHandle;
+    readonly run: <TResult = unknown>(id: string, args: unknown, options?: ToolApiRunOptions) => ToolRun<TResult>;
+    readonly subscribe: (listener: (snapshot: ToolApiSnapshot) => void) => () => void;
+    /** Revoke all providers and wait for their executors to exit. */
+    readonly dispose: () => Promise<void>;
+}
+/**
+ * Create the one effective Tool API capability for a Context/owner.
+ *
+ * Declarations are retained for inspection, while calls are admitted only
+ * through an active provider binding. The command tree and clients may cache
+ * the returned projection, but they never own executors or provider state.
+ */
+export declare function createToolApi(): ToolApi;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { createToolApi, type ToolApi, type ToolApiProviderHandle, type ToolApiProviderInput, type ToolApiProviderSnapshot, type ToolApiProviderState, type ToolApiRecord, type ToolApiRunOptions, type ToolApiSnapshot, } from './api.js';
 export { type ArtifactManifestValidation, createArtifactManifest, createArtifactRef, createPreviewArtifactManifest, createSnapshotRef, isSerializableValue, type PreviewArtifactIdentity, type PreviewArtifactKind, type PreviewArtifactManifest, type PreviewArtifactManifestEntry, type PreviewArtifactManifestValidation, type PreviewArtifactRole, type ToolArtifactIdentity, type ToolArtifactManifest, type ToolArtifactManifestEntry, validateArtifactManifest, validateArtifactRefs, validatePreviewArtifactManifest, } from './artifacts.js';
 export { createCapabilityResolver, createRealmCapabilityMatrix, createServiceCapability, defineToolCapability, type RealmBootstrapValidation, type RealmCapability, type RealmCapabilityInput, type RealmCapabilityMatrix, type ServiceAdmissionExpectation, type ServiceAdmissionRef, type ServiceCapability, validateRealmBootstrapPayload, } from './capability.js';
 export { type CarrierError, type CarrierErrorCode, type CarrierLease, type CarrierLeaseRequest, type CarrierOffer, type CarrierPhase, type CarrierResult, type CarrierState, type CarrierStateMachine, type CarrierStateMachineOptions, createCarrierStateMachine, } from './carrier.js';
@@ -10,4 +11,4 @@ export { createToolRuntime, defineTool, type ToolRuntime } from './runtime.js';
 export { isSnapshotRef, terminalSnapshot } from './snapshot.js';
 export { createExclusiveTiming, type ExclusiveTiming, type ExclusiveTimingResult, finishToolTiming, startToolTiming, } from './timing.js';
 export { type AuthenticatedCarrierTransport, type AuthenticatedCarrierTransportOptions, type AuthenticatedLoopbackTransport, type AuthenticatedLoopbackTransportOptions, type CarrierExecutionRequest, type CarrierTransport, CarrierTransportError, createAuthenticatedCarrierTransport, createAuthenticatedLoopbackTransport, createLoopbackTransport, type ServiceWireHandler, type ServiceWireRequest, } from './transport.js';
-export type { ArtifactRef, JsonPrimitive, JsonValue, SnapshotRef, ToolCapability, ToolCapabilityResolver, ToolCapabilityResult, ToolCleanupCensus, ToolCleanupReport, ToolContribution, ToolDescriptor, ToolDomainFailure, ToolEvidenceKind, ToolExecutionContext, ToolExecutor, ToolExecutorResult, ToolExecutorValue, ToolPhaseObservation, ToolPreviewContract, ToolRealm, ToolRecoveryAction, ToolResourceKind, ToolResourceObservation, ToolRun, ToolRunEvent, ToolRunOptions, ToolRuntimeError, ToolRuntimeErrorCode, ToolSchema, ToolSchemaResult, ToolSnapshotInput, ToolSubjectRef, ToolTerminal, ToolTiming, ToolTimingPhase, } from './types.js';
+export type { ArtifactRef, JsonPrimitive, JsonValue, SnapshotRef, ToolCallerIdentity, ToolCapability, ToolCapabilityResolver, ToolCapabilityResult, ToolCleanupCensus, ToolCleanupReport, ToolContribution, ToolDescriptor, ToolDomainFailure, ToolEvidenceKind, ToolExecutionContext, ToolExecutionOwner, ToolExecutor, ToolExecutorResult, ToolExecutorValue, ToolPhaseObservation, ToolPreviewContract, ToolRealm, ToolRecoveryAction, ToolResourceKind, ToolResourceObservation, ToolRun, ToolRunEvent, ToolRunOptions, ToolRuntimeError, ToolRuntimeErrorCode, ToolSchema, ToolSchemaResult, ToolSnapshotInput, ToolSubjectRef, ToolTerminal, ToolTiming, ToolTimingPhase, } from './types.js';