@ohos-ports/genkit 1.42.0-beta.0

package/src/client/agent.ts

@@ -0,0 +1,160 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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.
+ */
+
+import {
+  createAgentAPI,
+  type AgentAPI,
+  type AgentTransport,
+  type SnapshotLookup,
+} from '@genkit-ai/ai/agent-core';
+
+import type {
+  AgentInit,
+  AgentInput,
+  AgentOutput,
+  AgentStreamChunk,
+} from '@genkit-ai/ai';
+import type { SessionSnapshot } from '@genkit-ai/ai/session';
+import { runFlow, streamFlow } from './client.js';
+
+// Re-export the transport-agnostic agent-client surface so existing imports
+// from `genkit/beta/client` keep working.
+export {
+  AgentError,
+  type AgentAPI,
+  type AgentChat,
+  type AgentChunk,
+  type AgentInterrupt,
+  type AgentResponse,
+  type AgentTurn,
+  type DetachedTask,
+} from '@genkit-ai/ai/agent-core';
+
+// Re-export the JSON Patch helper so apps can apply a chunk's `customPatch` to
+// their own locally tracked copy of the agent's custom state.
+export { applyPatch, type JsonPatch } from '@genkit-ai/ai/json-patch';
+
+/**
+ * Options for {@link remoteAgent}.
+ */
+export interface RemoteAgentOptions {
+  /** Required. The agent endpoint. */
+  url: string;
+  /** Optional. Defaults to `${url}/getSnapshot`. */
+  getSnapshotUrl?: string;
+  /** Optional. Defaults to `${url}/abort`. */
+  abortUrl?: string;
+  /** Optional. Static headers, or a function called per request. */
+  headers?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+  /** Optional. Declares server- vs client-managed state; inferred otherwise. */
+  stateManagement?: 'server' | 'client';
+}
+
+// ---------------------------------------------------------------------------
+// remoteAgent factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a typed client for talking to a Genkit agent over HTTP.
+ *
+ * ```ts
+ * import { remoteAgent } from 'genkit/beta/client';
+ *
+ * const agent = remoteAgent<WeatherState>({
+ *   url: '/api/weatherAgent',
+ * });
+ * const chat = agent.chat();
+ * const res = await chat.send('Weather in Tokyo?').response;
+ * console.log(res.text);
+ * ```
+ */
+export function remoteAgent<State = unknown>(
+  options: RemoteAgentOptions
+): AgentAPI<State> {
+  const { url } = options;
+  const getSnapshotUrl = options.getSnapshotUrl ?? `${url}/getSnapshot`;
+  const abortUrl = options.abortUrl ?? `${url}/abort`;
+
+  const resolveHeaders = async (): Promise<
+    Record<string, string> | undefined
+  > => {
+    if (!options.headers) return undefined;
+    if (typeof options.headers === 'function') {
+      return options.headers();
+    }
+    return options.headers;
+  };
+
+  const transport: AgentTransport = {
+    stateManagement: options.stateManagement,
+
+    runTurn(
+      input: AgentInput,
+      init: AgentInit,
+      opts: { abortSignal: AbortSignal }
+    ) {
+      // Kick off the request lazily so headers can be resolved asynchronously.
+      const started = (async () => {
+        const headers = await resolveHeaders();
+        return streamFlow<AgentOutput, AgentStreamChunk, AgentInit>({
+          url,
+          input,
+          init,
+          headers,
+          abortSignal: opts.abortSignal,
+        });
+      })();
+
+      const output = (async () => {
+        const { output } = await started;
+        return output;
+      })();
+
+      const stream = (async function* (): AsyncIterable<AgentStreamChunk> {
+        const { stream: rawStream } = await started;
+        yield* rawStream;
+      })();
+
+      return { stream, output };
+    },
+
+    async getSnapshot(lookup: SnapshotLookup) {
+      const headers = await resolveHeaders();
+      return runFlow<SessionSnapshot<State> | undefined>({
+        url: getSnapshotUrl,
+        input: lookup,
+        headers,
+      });
+    },
+
+    async abort(snapshotId: string) {
+      const headers = await resolveHeaders();
+      const result = await runFlow<{
+        snapshotId: string;
+        status?: SessionSnapshot['status'];
+      }>({
+        url: abortUrl,
+        input: { snapshotId },
+        headers,
+      });
+      return result?.status;
+    },
+  };
+
+  return createAgentAPI<State>(transport);
+}

package/src/client/client.ts

@@ -0,0 +1,237 @@
+/**
+ * Copyright 2024 Google LLC
+ *
+ * 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.
+ */
+
+import { Channel, createTask } from '@genkit-ai/core/async';
+
+const __flowStreamDelimiter = '\n\n';
+
+/**
+ * Invoke and stream response from a deployed flow.
+ *
+ * For example:
+ *
+ * ```js
+ * import { streamFlow } from 'genkit/beta/client';
+ *
+ * const response = streamFlow({
+ *   url: 'https://my-flow-deployed-url',
+ *   input: 'foo',
+ * });
+ * for await (const chunk of response.stream) {
+ *   console.log(chunk);
+ * }
+ * console.log(await response.output);
+ * ```
+ */
+export function streamFlow<O = any, S = any, Init = any>({
+  url,
+  input,
+  init,
+  streamId,
+  headers,
+  abortSignal,
+}: {
+  /** URL of the deployed flow. */
+  url: string;
+  /** Flow input. */
+  input?: any;
+  /** Initialization data for the action. */
+  init?: Init;
+  /** Stream ID to connect to. */
+  streamId?: string;
+  /** A map of HTTP headers to be added to the HTTP call. */
+  headers?: Record<string, string>;
+  /** Abort signal to abort the request. */
+  abortSignal?: AbortSignal;
+}): {
+  readonly output: Promise<O>;
+  readonly stream: AsyncIterable<S>;
+  readonly streamId: Promise<string | null>;
+} {
+  const channel = new Channel<S>();
+  const streamIdTask = createTask<string | null>();
+
+  const operationPromise = __flowRunEnvelope({
+    url,
+    input,
+    init,
+    sendChunk: (c) => channel.send(c),
+    headers: streamId
+      ? { ...headers, 'x-genkit-stream-id': streamId }
+      : headers,
+    abortSignal,
+    responseCallback: (response) => {
+      streamIdTask.resolve(response.headers.get('x-genkit-stream-id'));
+    },
+  });
+  operationPromise.then(
+    () => channel.close(),
+    (err) => channel.error(err)
+  );
+
+  return {
+    output: operationPromise,
+    stream: channel,
+    streamId: streamIdTask.promise,
+  };
+}
+
+async function __flowRunEnvelope({
+  url,
+  input,
+  init,
+  sendChunk,
+  headers,
+  abortSignal,
+  responseCallback,
+}: {
+  url: string;
+  input: any;
+  init?: any;
+  sendChunk: (chunk: any) => void;
+  headers?: Record<string, string>;
+  abortSignal?: AbortSignal;
+  responseCallback?: (response: Response) => void;
+}) {
+  const response = await fetch(url, {
+    method: 'POST',
+    body: JSON.stringify({
+      data: input,
+      ...(init !== undefined && { init }),
+    }),
+    headers: {
+      Accept: 'text/event-stream',
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+    signal: abortSignal,
+  });
+  if (responseCallback) {
+    responseCallback(response);
+  }
+  if (response.status === 204) {
+    throw new Error('NOT_FOUND: Stream not found.');
+  }
+  if (response.status !== 200) {
+    throw new Error(
+      `Server returned: ${response.status}: ${await response.text()}`
+    );
+  }
+  if (!response.body) {
+    throw new Error('Response body is empty');
+  }
+  var reader = response.body.getReader();
+  var decoder = new TextDecoder();
+
+  let buffer = '';
+  while (true) {
+    const result = await reader.read();
+    const decodedValue = decoder.decode(result.value);
+    if (decodedValue) {
+      buffer += decodedValue;
+    }
+    // If buffer includes the delimiter that means we are still receiving chunks.
+    while (buffer.includes(__flowStreamDelimiter)) {
+      const chunk = JSON.parse(
+        buffer
+          .substring(0, buffer.indexOf(__flowStreamDelimiter))
+          .substring('data: '.length)
+      );
+      if (chunk.hasOwnProperty('message')) {
+        sendChunk(chunk.message);
+      } else if (chunk.hasOwnProperty('result')) {
+        return chunk.result;
+      } else if (chunk.hasOwnProperty('error')) {
+        throw new Error(
+          `${chunk.error.status}: ${chunk.error.message}\n${chunk.error.details}`
+        );
+      } else {
+        throw new Error('unknown chunk format: ' + JSON.stringify(chunk));
+      }
+      buffer = buffer.substring(
+        buffer.indexOf(__flowStreamDelimiter) + __flowStreamDelimiter.length
+      );
+    }
+  }
+  throw new Error('stream did not terminate correctly');
+}
+
+/**
+ * Invoke a deployed flow over HTTP(s).
+ *
+ * For example:
+ *
+ * ```js
+ * import { runFlow } from 'genkit/beta/client';
+ *
+ * const response = await runFlow({
+ *   url: 'https://my-flow-deployed-url',
+ *   input: 'foo',
+ * });
+ * console.log(await response);
+ * ```
+ */
+export async function runFlow<O = any, Init = any>({
+  url,
+  input,
+  init,
+  headers,
+  abortSignal,
+}: {
+  /** URL of the deployed flow. */
+  url: string;
+  /** Flow input. */
+  input?: any;
+  /** Initialization data for the action. */
+  init?: Init;
+  /** A map of HTTP headers to be added to the HTTP call. */
+  headers?: Record<string, string>;
+  /** Abort signal to abort the request. */
+  abortSignal?: AbortSignal;
+}): Promise<O> {
+  const response = await fetch(url, {
+    method: 'POST',
+    body: JSON.stringify({
+      data: input,
+      ...(init !== undefined && { init }),
+    }),
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+    signal: abortSignal,
+  });
+  if (response.status !== 200) {
+    throw new Error(
+      `Server returned: ${response.status}: ${await response.text()}`
+    );
+  }
+  const wrappedResult = (await response.json()) as
+    | { result: O }
+    | { error: unknown };
+  if ('error' in wrappedResult) {
+    if (typeof wrappedResult.error === 'string') {
+      throw new Error(wrappedResult.error);
+    }
+    // TODO: The callable protocol defines an HttpError that has a JSON format of
+    // details?: string
+    // httpErrorCode: { canonicalName: string }
+    // message: string
+    // Should we create a new error class that parses this and exposes it as fields?
+    throw new Error(JSON.stringify(wrappedResult.error));
+  }
+  return wrappedResult.result;
+}

package/src/client/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ *
+ * Copyright 2024 Google LLC
+ *
+ * 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.
+ */
+
+/**
+ * A simple, browser-safe client library for remotely running/streaming deployed Genkit flows.
+ *
+ * ```ts
+ * import { runFlow, streamFlow } from 'genkit/beta/client';
+ *
+ * const response = await runFlow({
+ *   url: 'https://my-flow-deployed-url',
+ *   input: 'foo',
+ * });
+ *
+ * const response = streamFlow({
+ *   url: 'https://my-flow-deployed-url',
+ *   input: 'foo',
+ * });
+ * for await (const chunk of response.stream) {
+ *   console.log(chunk);
+ * }
+ * console.log(await response.output);
+ * ```
+ *
+ * @module beta/client
+ */
+export {
+  AgentError,
+  applyPatch,
+  remoteAgent,
+  type AgentAPI,
+  type AgentChat,
+  type AgentChunk,
+  type AgentInterrupt,
+  type AgentResponse,
+  type AgentTurn,
+  type DetachedTask,
+  type JsonPatch,
+  type RemoteAgentOptions,
+} from './agent.js';
+
+export { runFlow, streamFlow } from './client.js';
+export type {
+  AgentFinishReason,
+  AgentInit,
+  AgentInput,
+  AgentOutput,
+  AgentStreamChunk,
+  Artifact,
+  GenerationUsage,
+  MessageData,
+  Part,
+  SessionSnapshot,
+  SessionState,
+  ToolRequestPart,
+  ToolResponsePart,
+} from './types.js';

package/src/client/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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.
+ */
+
+/**
+ * Type-only re-exports of the agent/generate contract types used by the agent
+ * client. Kept type-only so the browser-safe client pulls in no runtime code
+ * from `@genkit-ai/ai`.
+ *
+ * @module beta/client/types
+ */
+
+export type {
+  AgentInit,
+  AgentInput,
+  AgentOutput,
+  AgentStreamChunk,
+  GenerationUsage,
+  MessageData,
+  Part,
+  ToolRequestPart,
+  ToolResponsePart,
+} from '@genkit-ai/ai';
+export type {
+  AgentFinishReason,
+  Artifact,
+  SessionSnapshot,
+  SessionState,
+} from '@genkit-ai/ai/session';

package/src/common.ts

@@ -0,0 +1,175 @@
+/**
+ *
+ * Copyright 2024 Google LLC
+ *
+ * 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.
+ */
+
+export {
+  BaseDataPointSchema,
+  Document,
+  DocumentDataSchema,
+  GENKIT_UI_METADATA,
+  GENKIT_UI_WIDGETS,
+  GenerateResponse,
+  GenerateResponseChunk,
+  GenerationBlockedError,
+  GenerationCommonConfigSchema,
+  GenerationResponseError,
+  LlmResponseSchema,
+  LlmStatsSchema,
+  Message,
+  MessageSchema,
+  MiddlewareDescSchema,
+  MiddlewareRefSchema,
+  ModelReferenceSchema,
+  ModelRequestSchema,
+  ModelResponseSchema,
+  PartSchema,
+  RoleSchema,
+  ToolCallSchema,
+  ToolInterruptError,
+  ToolSchema,
+  dynamicResource,
+  embedderActionMetadata,
+  embedderRef,
+  evaluatorRef,
+  generateMiddleware,
+  indexerRef,
+  modelActionMetadata,
+  modelRef,
+  rerankerRef,
+  resource,
+  respondTool,
+  restartTool,
+  retrieverRef,
+  type DocumentData,
+  type DynamicResourceAction,
+  type EmbedderAction,
+  type EmbedderArgument,
+  type EmbedderInfo,
+  type EmbedderParams,
+  type EmbedderReference,
+  type Embedding,
+  type EvalResponses,
+  type EvaluatorAction,
+  type EvaluatorInfo,
+  type EvaluatorParams,
+  type EvaluatorReference,
+  type ExecutablePrompt,
+  type GenerateMiddleware,
+  type GenerateMiddlewareDef,
+  type GenerateOptions,
+  type GenerateRequest,
+  type GenerateRequestData,
+  type GenerateResponseChunkData,
+  type GenerateResponseData,
+  type GenerateStreamOptions,
+  type GenerateStreamResponse,
+  type GenerationUsage,
+  type IndexerAction,
+  type IndexerArgument,
+  type IndexerInfo,
+  type IndexerParams,
+  type IndexerReference,
+  type InterruptConfig,
+  type LlmResponse,
+  type LlmStats,
+  type MediaPart,
+  type MessageData,
+  type MiddlewareDesc,
+  type MiddlewareRef,
+  type ModelArgument,
+  type ModelReference,
+  type ModelRequest,
+  type ModelResponseData,
+  type MultipartToolAction,
+  type OperationOptions,
+  type OutputOptions,
+  type Part,
+  type PromptAction,
+  type PromptConfig,
+  type PromptGenerateOptions,
+  type RankedDocument,
+  type RerankerAction,
+  type RerankerArgument,
+  type RerankerInfo,
+  type RerankerParams,
+  type RerankerReference,
+  type ResourceAction,
+  type ResumeOptions,
+  type RetrieverAction,
+  type RetrieverArgument,
+  type RetrieverInfo,
+  type RetrieverParams,
+  type RetrieverReference,
+  type Role,
+  type Tool,
+  type ToolAction,
+  type ToolArgument,
+  type ToolCall,
+  type ToolChoice,
+  type ToolConfig,
+  type ToolRequest,
+  type ToolRequestPart,
+  type ToolResponse,
+  type ToolResponsePart,
+} from '@genkit-ai/ai';
+export { dynamicTool, tool } from '@genkit-ai/ai/tool';
+export {
+  GENKIT_CLIENT_HEADER,
+  GENKIT_VERSION,
+  GenkitError,
+  OperationSchema,
+  ReflectionServer,
+  StatusCodes,
+  StatusNameSchema,
+  StatusSchema,
+  UserFacingError,
+  annotateSchema,
+  defineJsonSchema,
+  defineSchema,
+  getClientHeader,
+  getCurrentEnv,
+  getGenkitRuntimeConfig,
+  getStreamingCallback,
+  isDevEnv,
+  resetGenkitRuntimeConfig,
+  runWithStreamingCallback,
+  setGenkitRuntimeConfig,
+  z,
+  type Action,
+  type ActionContext,
+  type ActionMetadata,
+  type DynamicActionProviderAction,
+  type ErrorResponseMetadata,
+  type Flow,
+  type FlowConfig,
+  type FlowFn,
+  type FlowSideChannel,
+  type GenkitRuntimeConfig,
+  type JSONSchema,
+  type JSONSchema7,
+  type Middleware,
+  type Operation,
+  type ReflectionServerOptions,
+  type RunActionResponse,
+  type Status,
+  type StatusName,
+  type StreamingCallback,
+  type StreamingResponse,
+  type TelemetryConfig,
+} from '@genkit-ai/core';
+import { initNodeFeatures } from '@genkit-ai/core/node';
+
+initNodeFeatures();