@zhin.js/ai-provider 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @zhin.js/ai-provider
 
-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.
+Plugin Runtime integration for the AI Provider contracts in `@zhin.js/ai/provider`.
+
+Provider plugins publish all their definitions in one setup call:
+`provideAiProviders(context.resources, [definition, anotherDefinition])`.
+Repeated registration in the same Scope is rejected; declarations become immutable when setup seals.
+Definitions keep their exact plugin owner. Host integrations resolve them from the operation's
+held snapshot with `createSnapshotProviderResolver`; another plugin with the same driver name
+cannot replace a saved Service's owner.
+
+This package owns no model loop, accounts, credentials, network access or global registration.
+An operation's `aiInferenceClientToken` contains only its already authorized `InferenceClient`.
+SDKs remain optional dependencies of the actual Provider implementation.
+
+Commands and Agent Tools receive independent operation clients through `context.use(aiInferenceClientToken)`.
+The Host supplies the exact generation, identity and model graph; callers cannot pass an owner or account override.
+Checking availability or acquiring the client does not open a model or consume quota. Streams start only when
+consumed, and their owner closes escaped or unused runs when execution ends. A Tool never closes its parent turn.
+
+Driver `profileSchema({service, model})` describes and validates the selected protocol's actual parameters.
+Use one typed pure schema resolver for parsing and Console input metadata; keep Account secrets out of both.

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+import { type PluginId, type RuntimeSnapshot, type Scope, type SnapshotLease, type SnapshotReader } from '@zhin.js/plugin-runtime';
+import { type InferenceClient, type ProviderDefinition, type ProviderDriverResolver } from '@zhin.js/ai/provider';
+export * from './lazy-client.js';
+export * from './usage.js';
+export interface ProvidedAiProvider {
+    readonly owner: PluginId;
+    readonly definition: ProviderDefinition<unknown, unknown>;
+}
+/** Declarations only; no accounts, mutable credentials or process-wide registry. */
+export declare const aiProviderDefinitionsToken: import("@zhin.js/plugin-runtime").Token<readonly ProvidedAiProvider[]>;
+/** Installed only on an actual operation with its already bound principal. */
+export declare const aiInferenceClientToken: import("@zhin.js/plugin-runtime").Token<InferenceClient>;
+export declare function provideAiProviders(resources: Scope, definitions: readonly ProviderDefinition<unknown, unknown>[]): void;
+/** Pure projection of the supplied held snapshot; inherited declarations are not new owners. */
+export declare function listSnapshotAiProviders(snapshot: RuntimeSnapshot): readonly ProvidedAiProvider[];
+export declare function describeSnapshotAiProvider(input: {
+    readonly snapshot: RuntimeSnapshot;
+    readonly id: string;
+    readonly owner?: string;
+}): ProvidedAiProvider;
+export interface SnapshotProviderResolverOptions {
+    readonly snapshots: SnapshotReader;
+    /** The held operation generation, never a lookup of the latest snapshot. */
+    readonly lease: SnapshotLease;
+}
+export declare function createSnapshotProviderResolver(options: SnapshotProviderResolverOptions): ProviderDriverResolver;

package/lib/index.js

@@ -0,0 +1,76 @@
+import { createToken } from '@zhin.js/plugin-runtime';
+import { ProviderError } from '@zhin.js/ai/provider';
+export * from './lazy-client.js';
+export * from './usage.js';
+/** Declarations only; no accounts, mutable credentials or process-wide registry. */
+export const aiProviderDefinitionsToken = createToken('zhin.ai.provider-definitions');
+/** Installed only on an actual operation with its already bound principal. */
+export const aiInferenceClientToken = createToken('zhin.ai.inference-client');
+export function provideAiProviders(resources, definitions) {
+    const names = new Set();
+    const entries = definitions.map(definition => {
+        if (!definition.id || names.has(definition.id))
+            throw new Error('Duplicate or empty AI Provider definition');
+        names.add(definition.id);
+        return Object.freeze({ owner: resources.owner, definition });
+    });
+    resources.provide(aiProviderDefinitionsToken, Object.freeze(entries));
+}
+/** Pure projection of the supplied held snapshot; inherited declarations are not new owners. */
+export function listSnapshotAiProviders(snapshot) {
+    const result = [];
+    for (const [owner, resources] of snapshot.resources) {
+        if (!snapshot.tree.has(owner))
+            continue;
+        const entries = resources.get(aiProviderDefinitionsToken.id);
+        for (const entry of entries ?? [])
+            if (entry.owner === owner)
+                result.push(entry);
+    }
+    return Object.freeze(result);
+}
+export function describeSnapshotAiProvider(input) {
+    const matches = listSnapshotAiProviders(input.snapshot).filter(entry => entry.definition.id === input.id && (input.owner === undefined || entry.owner === input.owner));
+    const matched = matches[0];
+    if (!matched)
+        throw new ProviderError('driver-unavailable');
+    if (matches.length !== 1)
+        throw new Error('AI Provider driver name is ambiguous; select an exact owner');
+    return matched;
+}
+export function createSnapshotProviderResolver(options) {
+    return {
+        async acquire({ service, signal }) {
+            signal.throwIfAborted();
+            const lease = options.snapshots.retain(options.lease);
+            try {
+                const snapshot = lease.value;
+                const owner = service.driver.owner;
+                if (!snapshot.tree.has(owner))
+                    throw new ProviderError('driver-unavailable');
+                const entries = snapshot.resources.get(owner)?.get(aiProviderDefinitionsToken.id);
+                const provided = entries?.find(entry => entry.owner === owner && entry.definition.id === service.driver.id);
+                if (!provided)
+                    throw new ProviderError('driver-unavailable');
+                if (provided.definition.contractVersion !== service.driver.contractVersion)
+                    throw new ProviderError('driver-contract-mismatch');
+                let released = false;
+                return {
+                    definition: provided.definition,
+                    reference: Object.freeze({ ...service.driver }),
+                    release() {
+                        if (released)
+                            return;
+                        released = true;
+                        lease.release();
+                    },
+                };
+            }
+            catch (error) {
+                lease.release();
+                throw error;
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { createToken, type PluginId, type RuntimeSnapshot, type Scope, type SnapshotLease, type SnapshotReader } from '@zhin.js/plugin-runtime';\nimport { ProviderError, type InferenceClient, type ProviderDefinition, type ProviderDriverResolver } from '@zhin.js/ai/provider';\nexport * from './lazy-client.js';\nexport * from './usage.js';\n\nexport interface ProvidedAiProvider {\n  readonly owner: PluginId;\n  readonly definition: ProviderDefinition<unknown, unknown>;\n}\n\n/** Declarations only; no accounts, mutable credentials or process-wide registry. */\nexport const aiProviderDefinitionsToken = createToken<readonly ProvidedAiProvider[]>('zhin.ai.provider-definitions');\n\n/** Installed only on an actual operation with its already bound principal. */\nexport const aiInferenceClientToken = createToken<InferenceClient>('zhin.ai.inference-client');\n\nexport function provideAiProviders(\n  resources: Scope,\n  definitions: readonly ProviderDefinition<unknown, unknown>[],\n): void {\n  const names = new Set<string>();\n  const entries = definitions.map(definition => {\n    if (!definition.id || names.has(definition.id)) throw new Error('Duplicate or empty AI Provider definition');\n    names.add(definition.id);\n    return Object.freeze({ owner: resources.owner, definition });\n  });\n  resources.provide(aiProviderDefinitionsToken, Object.freeze(entries));\n}\n\n/** Pure projection of the supplied held snapshot; inherited declarations are not new owners. */\nexport function listSnapshotAiProviders(snapshot: RuntimeSnapshot): readonly ProvidedAiProvider[] {\n  const result: ProvidedAiProvider[] = [];\n  for (const [owner, resources] of snapshot.resources) {\n    if (!snapshot.tree.has(owner)) continue;\n    const entries = resources.get(aiProviderDefinitionsToken.id) as readonly ProvidedAiProvider[] | undefined;\n    for (const entry of entries ?? []) if (entry.owner === owner) result.push(entry);\n  }\n  return Object.freeze(result);\n}\n\nexport function describeSnapshotAiProvider(input: {\n  readonly snapshot: RuntimeSnapshot;\n  readonly id: string;\n  readonly owner?: string;\n}): ProvidedAiProvider {\n  const matches = listSnapshotAiProviders(input.snapshot).filter(entry =>\n    entry.definition.id === input.id && (input.owner === undefined || entry.owner === input.owner));\n  const matched = matches[0];\n  if (!matched) throw new ProviderError('driver-unavailable');\n  if (matches.length !== 1) throw new Error('AI Provider driver name is ambiguous; select an exact owner');\n  return matched;\n}\n\nexport interface SnapshotProviderResolverOptions {\n  readonly snapshots: SnapshotReader;\n  /** The held operation generation, never a lookup of the latest snapshot. */\n  readonly lease: SnapshotLease;\n}\n\nexport function createSnapshotProviderResolver(options: SnapshotProviderResolverOptions): ProviderDriverResolver {\n  return {\n    async acquire({ service, signal }) {\n      signal.throwIfAborted();\n      const lease = options.snapshots.retain(options.lease);\n      try {\n        const snapshot = lease.value;\n        const owner = service.driver.owner as PluginId;\n        if (!snapshot.tree.has(owner)) throw new ProviderError('driver-unavailable');\n        const entries = snapshot.resources.get(owner)?.get(aiProviderDefinitionsToken.id) as readonly ProvidedAiProvider[] | undefined;\n        const provided = entries?.find(entry => entry.owner === owner && entry.definition.id === service.driver.id);\n        if (!provided) throw new ProviderError('driver-unavailable');\n        if (provided.definition.contractVersion !== service.driver.contractVersion) throw new ProviderError('driver-contract-mismatch');\n        let released = false;\n        return {\n          definition: provided.definition,\n          reference: Object.freeze({ ...service.driver }),\n          release() {\n            if (released) return;\n            released = true;\n            lease.release();\n          },\n        };\n      } catch (error) {\n        lease.release();\n        throw error;\n      }\n    },\n  };\n}\n"]}

package/lib/lazy-client.d.ts

@@ -0,0 +1,13 @@
+import { type InferenceClient } from '@zhin.js/ai/provider';
+import type { InferenceUsageAccounting } from './usage.js';
+export interface LazyInferenceClientOptions {
+    readonly signal: AbortSignal;
+    /** Host closure owns the exact lease, identity and graph capture; callers supply none of them. */
+    readonly open: (input: Readonly<{
+        signal: AbortSignal;
+    }>) => Promise<InferenceClient>;
+    readonly accounting?: InferenceUsageAccounting;
+    readonly onCleanupError?: (error: unknown) => void;
+}
+/** One operation's lazy client. Returning it from execute does not transfer its lifetime. */
+export declare function createLazyInferenceClient(options: LazyInferenceClientOptions): InferenceClient;

package/lib/lazy-client.js

@@ -0,0 +1,156 @@
+import { assistantText } from '@zhin.js/ai';
+import { OwnedLanguageRun, ProviderError } from '@zhin.js/ai/provider';
+function usage(message) {
+    const reported = message.usage.reported;
+    const total = reported ? reported.totalTokens === true || reported.input === true && reported.output === true
+        ? message.usage.totalTokens : undefined : message.usage.totalTokens > 0 ? message.usage.totalTokens : undefined;
+    return { ...(total !== undefined ? { totalTokens: total } : {}), text: assistantText(message) };
+}
+/** One operation's lazy client. Returning it from execute does not transfer its lifetime. */
+export function createLazyInferenceClient(options) {
+    const controller = new AbortController();
+    const signal = AbortSignal.any([controller.signal, options.signal]);
+    const pending = new Set(), runs = new Set();
+    let opening, closing, underlyingClose;
+    let closed = false;
+    const report = (error) => { try {
+        options.onCleanupError?.(error);
+    }
+    catch { /* diagnostics are not business results */ } };
+    const dispose = (client) => underlyingClose ??= Promise.resolve().then(() => client.close()).catch(report);
+    function assertOpen() {
+        if (closed)
+            throw new ProviderError('operation-closed');
+        signal.throwIfAborted();
+    }
+    function get() {
+        assertOpen();
+        return opening ??= Promise.resolve().then(() => { assertOpen(); return options.open({ signal }); }).then(async (client) => {
+            if (closed || signal.aborted) {
+                await dispose(client);
+                throw new ProviderError('operation-closed');
+            }
+            return client;
+        });
+    }
+    function track(promise) {
+        pending.add(promise);
+        void promise.then(() => pending.delete(promise), () => pending.delete(promise));
+        return promise;
+    }
+    async function invoke(request, execute, outcome) {
+        assertOpen();
+        const invocation = options.accounting?.begin(request);
+        try {
+            const operation = async () => execute(await get());
+            const result = await (invocation ? invocation.run(operation) : operation());
+            try {
+                invocation?.finish(outcome(result));
+            }
+            catch (error) {
+                report(error);
+            }
+            return result;
+        }
+        finally {
+            try {
+                invocation?.close();
+            }
+            catch (error) {
+                report(error);
+            }
+        }
+    }
+    async function close() {
+        if (closing)
+            return closing;
+        closed = true;
+        options.signal.removeEventListener('abort', stop);
+        controller.abort(new ProviderError('operation-closed'));
+        return closing = (async () => {
+            await Promise.allSettled([...runs].map(run => run.close()));
+            await Promise.allSettled([...pending]);
+            if (opening)
+                await opening.then(dispose, () => undefined);
+        })();
+    }
+    const stop = () => { void close().catch(report); };
+    options.signal.addEventListener('abort', stop, { once: true });
+    if (options.signal.aborted)
+        stop();
+    const client = {
+        list(input) { return track((async () => (await get()).list(input))()); },
+        generate(input) {
+            return track(invoke({ kind: 'language', request: input.request }, underlying => underlying.generate({ ...input,
+                signal: input.signal ? AbortSignal.any([signal, input.signal]) : signal }), usage));
+        },
+        evaluate(input) {
+            return track(invoke({ kind: 'decision', state: input.state, questions: input.questions }, underlying => underlying.evaluate({ ...input,
+                signal: input.signal ? AbortSignal.any([signal, input.signal]) : signal }), result => ({ totalTokens: result.usage.inputTokens + result.usage.outputTokens })));
+        },
+        generateImage(input) {
+            return track(invoke({ kind: 'image', request: input.request }, underlying => underlying.generateImage({ ...input,
+                signal: input.signal ? AbortSignal.any([signal, input.signal]) : signal }), () => ({})));
+        },
+        async stream(input) {
+            assertOpen();
+            const streamController = new AbortController();
+            const streamSignal = AbortSignal.any([signal, streamController.signal, ...(input.signal ? [input.signal] : [])]);
+            let invocation, source, released;
+            const cancel = () => streamController.abort(streamSignal.reason);
+            const release = () => released ??= (async () => {
+                runs.delete(run);
+                streamSignal.removeEventListener('abort', cancel);
+                try {
+                    await source?.close();
+                }
+                catch (error) {
+                    report(error);
+                }
+                try {
+                    invocation?.close();
+                }
+                catch (error) {
+                    report(error);
+                }
+            })();
+            async function* events() {
+                assertOpen();
+                streamSignal.throwIfAborted();
+                invocation = options.accounting?.begin({ kind: 'language', request: input.request });
+                const within = (operation) => invocation ? invocation.run(operation) : operation();
+                try {
+                    source = await within(async () => (await get()).stream({ ...input, signal: streamSignal }));
+                    const iterator = source[Symbol.asyncIterator]();
+                    for (;;) {
+                        const next = await within(() => iterator.next());
+                        if (next.done)
+                            return;
+                        if (next.value.type === 'done' && next.value.message) {
+                            try {
+                                invocation?.finish(usage(next.value.message));
+                            }
+                            catch (error) {
+                                report(error);
+                            }
+                        }
+                        yield next.value;
+                    }
+                }
+                finally {
+                    await release();
+                }
+            }
+            const run = new OwnedLanguageRun({ source: events(), controller: streamController, release, project: value => value, onCleanupError: report });
+            runs.add(run);
+            streamSignal.addEventListener('abort', cancel, { once: true });
+            if (streamSignal.aborted)
+                cancel();
+            return run;
+        },
+        close,
+        [Symbol.asyncDispose]: close,
+    };
+    return Object.freeze(client);
+}
+//# sourceMappingURL=lazy-client.js.map

package/lib/lazy-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-client.js","sourceRoot":"","sources":["../src/lazy-client.ts"],"names":[],"mappings":"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","sourcesContent":["import { assistantText, type AssistantMessage, type AssistantStreamEvent } from '@zhin.js/ai';\nimport { OwnedLanguageRun, ProviderError, type InferenceClient, type LanguageRun } from '@zhin.js/ai/provider';\nimport type { InferenceUsageAccounting, InferenceUsageInvocation, InferenceUsageOutcome, InferenceUsageRequest } from './usage.js';\n\nexport interface LazyInferenceClientOptions {\n  readonly signal: AbortSignal;\n  /** Host closure owns the exact lease, identity and graph capture; callers supply none of them. */\n  readonly open: (input: Readonly<{ signal: AbortSignal }>) => Promise<InferenceClient>;\n  readonly accounting?: InferenceUsageAccounting;\n  readonly onCleanupError?: (error: unknown) => void;\n}\nfunction usage(message: AssistantMessage): InferenceUsageOutcome {\n  const reported = message.usage.reported;\n  const total = reported ? reported.totalTokens === true || reported.input === true && reported.output === true\n    ? message.usage.totalTokens : undefined : message.usage.totalTokens > 0 ? message.usage.totalTokens : undefined;\n  return { ...(total !== undefined ? { totalTokens: total } : {}), text: assistantText(message) };\n}\n\n/** One operation's lazy client. Returning it from execute does not transfer its lifetime. */\nexport function createLazyInferenceClient(options: LazyInferenceClientOptions): InferenceClient {\n  const controller = new AbortController();\n  const signal = AbortSignal.any([controller.signal, options.signal]);\n  const pending = new Set<Promise<unknown>>(), runs = new Set<LanguageRun>();\n  let opening: Promise<InferenceClient> | undefined, closing: Promise<void> | undefined, underlyingClose: Promise<void> | undefined;\n  let closed = false;\n  const report = (error: unknown) => { try { options.onCleanupError?.(error); } catch { /* diagnostics are not business results */ } };\n  const dispose = (client: InferenceClient) => underlyingClose ??= Promise.resolve().then(() => client.close()).catch(report);\n  function assertOpen() {\n    if (closed) throw new ProviderError('operation-closed');\n    signal.throwIfAborted();\n  }\n  function get(): Promise<InferenceClient> {\n    assertOpen();\n    return opening ??= Promise.resolve().then(() => { assertOpen(); return options.open({ signal }); }).then(async client => {\n      if (closed || signal.aborted) { await dispose(client); throw new ProviderError('operation-closed'); }\n      return client;\n    });\n  }\n  function track<T>(promise: Promise<T>): Promise<T> {\n    pending.add(promise); void promise.then(() => pending.delete(promise), () => pending.delete(promise));\n    return promise;\n  }\n  async function invoke<T>(request: InferenceUsageRequest, execute: (client: InferenceClient) => Promise<T>, outcome: (result: T) => InferenceUsageOutcome): Promise<T> {\n    assertOpen();\n    const invocation = options.accounting?.begin(request);\n    try {\n      const operation = async () => execute(await get());\n      const result = await (invocation ? invocation.run(operation) : operation());\n      try { invocation?.finish(outcome(result)); } catch (error) { report(error); }\n      return result;\n    } finally { try { invocation?.close(); } catch (error) { report(error); } }\n  }\n  async function close(): Promise<void> {\n    if (closing) return closing;\n    closed = true; options.signal.removeEventListener('abort', stop);\n    controller.abort(new ProviderError('operation-closed'));\n    return closing = (async () => {\n      await Promise.allSettled([...runs].map(run => run.close()));\n      await Promise.allSettled([...pending]);\n      if (opening) await opening.then(dispose, () => undefined);\n    })();\n  }\n  const stop = () => { void close().catch(report); };\n  options.signal.addEventListener('abort', stop, { once: true });\n  if (options.signal.aborted) stop();\n  const client: InferenceClient = {\n    list(input) { return track((async () => (await get()).list(input))()); },\n    generate(input) {\n      return track(invoke({ kind: 'language', request: input.request }, underlying => underlying.generate({ ...input,\n        signal: input.signal ? AbortSignal.any([signal, input.signal]) : signal }), usage));\n    },\n    evaluate(input) {\n      return track(invoke({ kind: 'decision', state: input.state, questions: input.questions }, underlying => underlying.evaluate({ ...input,\n        signal: input.signal ? AbortSignal.any([signal, input.signal]) : signal }), result => ({ totalTokens: result.usage.inputTokens + result.usage.outputTokens })));\n    },\n    generateImage(input) {\n      return track(invoke({ kind: 'image', request: input.request }, underlying => underlying.generateImage({ ...input,\n        signal: input.signal ? AbortSignal.any([signal, input.signal]) : signal }), () => ({})));\n    },\n    async stream(input) {\n      assertOpen();\n      const streamController = new AbortController();\n      const streamSignal = AbortSignal.any([signal, streamController.signal, ...(input.signal ? [input.signal] : [])]);\n      let invocation: InferenceUsageInvocation | undefined, source: LanguageRun | undefined, released: Promise<void> | undefined;\n      const cancel = () => streamController.abort(streamSignal.reason);\n      const release = () => released ??= (async () => {\n        runs.delete(run);\n        streamSignal.removeEventListener('abort', cancel);\n        try { await source?.close(); } catch (error) { report(error); }\n        try { invocation?.close(); } catch (error) { report(error); }\n      })();\n      async function* events(): AsyncGenerator<AssistantStreamEvent> {\n        assertOpen(); streamSignal.throwIfAborted();\n        invocation = options.accounting?.begin({ kind: 'language', request: input.request });\n        const within = <T>(operation: () => Promise<T>) => invocation ? invocation.run(operation) : operation();\n        try {\n          source = await within(async () => (await get()).stream({ ...input, signal: streamSignal }));\n          const iterator = source[Symbol.asyncIterator]();\n          for (;;) {\n            const next = await within(() => iterator.next());\n            if (next.done) return;\n            if (next.value.type === 'done' && next.value.message) {\n              try { invocation?.finish(usage(next.value.message)); } catch (error) { report(error); }\n            }\n            yield next.value;\n          }\n        } finally { await release(); }\n      }\n      const run = new OwnedLanguageRun({ source: events(), controller: streamController, release, project: value => value, onCleanupError: report });\n      runs.add(run);\n      streamSignal.addEventListener('abort', cancel, { once: true });\n      if (streamSignal.aborted) cancel();\n      return run;\n    },\n    close,\n    [Symbol.asyncDispose]: close,\n  };\n  return Object.freeze(client);\n}\n"]}

package/lib/usage.d.ts

@@ -0,0 +1,30 @@
+import type { DecisionQuestions, JsonValue, GenerateImageInput, LanguageRequest } from '@zhin.js/ai/provider';
+/** Semantic input only. Account identity and quota subjects are supplied privately by Host. */
+export type InferenceUsageRequest = Readonly<{
+    kind: 'language';
+    request: LanguageRequest;
+}> | Readonly<{
+    kind: 'decision';
+    state: JsonValue;
+    questions: DecisionQuestions;
+}> | Readonly<{
+    kind: 'image';
+    request: GenerateImageInput['request'];
+}>;
+export interface InferenceUsageOutcome {
+    /** Absent means unknown; zero is a reported zero, never an implicit estimate. */
+    readonly totalTokens?: number;
+    readonly text?: string;
+}
+export interface InferenceUsageInvocation {
+    /** Preserve this call's private attribution through actual asynchronous transport work. */
+    run<T>(execute: () => Promise<T>): Promise<T>;
+    finish(outcome: InferenceUsageOutcome): void;
+    close(): void;
+}
+export interface InferenceUsageAccounting {
+    /** Admission may deny. Merely constructing a lazy client/run never calls this. */
+    begin(input: InferenceUsageRequest): InferenceUsageInvocation;
+    /** Called immediately before the actual inference transport submits, not for OAuth or catalogues. */
+    submitted(): void;
+}

package/lib/usage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=usage.js.map

package/lib/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"","sourcesContent":["import type { DecisionQuestions, JsonValue, GenerateImageInput, LanguageRequest } from '@zhin.js/ai/provider';\n\n/** Semantic input only. Account identity and quota subjects are supplied privately by Host. */\nexport type InferenceUsageRequest =\n  | Readonly<{ kind: 'language'; request: LanguageRequest }>\n  | Readonly<{ kind: 'decision'; state: JsonValue; questions: DecisionQuestions }>\n  | Readonly<{ kind: 'image'; request: GenerateImageInput['request'] }>;\nexport interface InferenceUsageOutcome {\n  /** Absent means unknown; zero is a reported zero, never an implicit estimate. */\n  readonly totalTokens?: number;\n  readonly text?: string;\n}\nexport interface InferenceUsageInvocation {\n  /** Preserve this call's private attribution through actual asynchronous transport work. */\n  run<T>(execute: () => Promise<T>): Promise<T>;\n  finish(outcome: InferenceUsageOutcome): void;\n  close(): void;\n}\nexport interface InferenceUsageAccounting {\n  /** Admission may deny. Merely constructing a lazy client/run never calls this. */\n  begin(input: InferenceUsageRequest): InferenceUsageInvocation;\n  /** Called immediately before the actual inference transport submits, not for OAuth or catalogues. */\n  submitted(): void;\n}\n"]}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@zhin.js/ai-provider",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Owner-scoped AI Provider registration for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@zhin.js/ai": "1.1.51",
+    "@zhin.js/plugin-runtime": "1.1.20"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/ai-provider"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/ai-provider/tests"
+  }
 }