@anureo/sdk 0.0.0-stage → 0.3.0

package/src/errors.js

@@ -0,0 +1,63 @@
+/**
+ * Inspect SDK or adapter failures by code and outcome. Producers must supply safe messages and
+ * details. Check outcomeUnknown before retrying an operation that may already have taken effect.
+ */
+export class HarnessSdkError extends Error {
+    code;
+    retryable;
+    outcomeUnknown;
+    details;
+    /**
+     * Create a failure with an already-sanitized code, message and diagnostics. The message defaults
+     * to the code, both flags default to false, and details are retained by reference.
+     */
+    constructor(
+    /** Safe machine-readable failure code selected by the owning subsystem. */
+    code, 
+    /** Caller-safe message; never populate this with an unfiltered native cause. */
+    message = code, 
+    /** Whether the operation’s safe failure policy permits a caller retry. */
+    retryable = false, 
+    /** Native acceptance/completion could not be established; retry may duplicate work. */
+    outcomeUnknown = false, 
+    /** Already-sanitized structured diagnostics supplied by the owning subsystem. */
+    details) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.outcomeUnknown = outcomeUnknown;
+        this.details = details;
+    }
+    /** Error name used in diagnostics. */
+    name = "HarnessSdkError";
+}
+/**
+ * Normalize a failure for SDK or adapter callers. Return existing HarnessSdkError instances by
+ * identity. For other objects with a code matching A-Z followed by up to 80 uppercase letters,
+ * digits or underscores, use the code as the message and copy only literal-true flags. A present
+ * outcomeUnknown property on such an object overrides the supplied default. Other causes use
+ * fallback (HARNESS_ERROR by default) as both code and message, with retryable false and the
+ * supplied outcomeUnknown default. Supply a safe fallback. Property access can throw if the
+ * cause has throwing getters or proxy traps.
+ *
+ * Called by:
+ * - Session.onRequestFailed to choose recovery state and publish safe submission failure status.
+ * - InteractionRegistry.deliverResponse to classify responder or publication failures for the
+ *   interaction waiter and, during delivery, for publication of an unknown outcome.
+ * - checkRelease in structured-output/errors to throw safe failures after cleanup attempts settle.
+ * Public consumers can apply the same normalization; callers own propagation, retries and cleanup.
+ */
+export function sdkError(cause, fallback = "HARNESS_ERROR", outcomeUnknown = false) {
+    if (cause instanceof HarnessSdkError)
+        return cause;
+    if (cause && typeof cause === "object" && "code" in cause
+        && typeof cause.code === "string" && /^[A-Z][A-Z0-9_]{0,80}$/.test(cause.code)) {
+        const code = cause.code;
+        const message = cause.code;
+        const retryable = "retryable" in cause && cause.retryable === true;
+        const resolvedOutcomeUnknown = "outcomeUnknown" in cause ? cause.outcomeUnknown === true : outcomeUnknown;
+        return new HarnessSdkError(code, message, retryable, resolvedOutcomeUnknown);
+    }
+    // Do not include raw backend errors: they may contain credentials or private answers.
+    return new HarnessSdkError(fallback, fallback, false, outcomeUnknown);
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+export { createClient, Client } from "./client.js";
+export { Session } from "./session.js";
+export type { ClientOptions, InteractionHandlers, SubmitOptions } from "./client-options.js";
+export { Turn } from "./turn.js";
+export type { EventSubscriptionOptions, Input, RequestOptions, TurnResult } from "./types.js";
+export type * from "./ports.js";
+export * from "./errors.js";
+export { waitForRequest } from "./request.js";
+/** Adapter/observer buffering primitives, also available from the package's queue entry point. */
+export * from "./queue.js";
+/** Session-local native ID mapping implementation. */
+export * from "./adapter/identity.js";
+/** Interaction settlement and replay implementation used by Session. */
+export * from "./lifecycle/interactions.js";
+/** Adapter subprocess handles and launch helpers, also available from the process entry point; callers drain output and await handle disposal. */
+export * from "./process.js";
+/** Marked-secret projection implementation used by Session. */
+export * from "./privacy/secrets.js";
+/**
+ * Forward LogTape's host logging controls without adding SDK ownership. The exported dispose is
+ * LogTape's logging teardown; native resources are released through Client.dispose separately.
+ */
+export { configure, configureSync, dispose, disposeSync, drain, getLogger, reset, resetSync } from '@logtape/logtape';
+/** LogTape types for hosts configuring logging through the forwarded functions above. */
+export type { Config, LogLevel, LogRecord, Logger, Sink } from '@logtape/logtape';
+/** Explicit unattended approval policy for hosts; never enabled by Client automatically. */
+export { approveWithNarrowestScope } from "./lifecycle/approval.js";

package/src/index.js

@@ -0,0 +1,23 @@
+// Root entry point for the application API, adapter contracts and host utilities.
+export { createClient, Client } from "./client.js";
+export { Session } from "./session.js";
+export { Turn } from "./turn.js";
+export * from "./errors.js";
+export { waitForRequest } from "./request.js";
+/** Adapter/observer buffering primitives, also available from the package's queue entry point. */
+export * from "./queue.js";
+/** Session-local native ID mapping implementation. */
+export * from "./adapter/identity.js";
+/** Interaction settlement and replay implementation used by Session. */
+export * from "./lifecycle/interactions.js";
+/** Adapter subprocess handles and launch helpers, also available from the process entry point; callers drain output and await handle disposal. */
+export * from "./process.js";
+/** Marked-secret projection implementation used by Session. */
+export * from "./privacy/secrets.js";
+/**
+ * Forward LogTape's host logging controls without adding SDK ownership. The exported dispose is
+ * LogTape's logging teardown; native resources are released through Client.dispose separately.
+ */
+export { configure, configureSync, dispose, disposeSync, drain, getLogger, reset, resetSync } from '@logtape/logtape';
+/** Explicit unattended approval policy for hosts; never enabled by Client automatically. */
+export { approveWithNarrowestScope } from "./lifecycle/approval.js";

package/src/lifecycle/approval.d.ts

@@ -0,0 +1,16 @@
+import type { InteractionRequested, InteractionResponse } from '@anureo/protocol';
+/**
+ * Select an advertised grant for unattended approval. Prefer allow-once, then session, then
+ * rule grants. When several options have the same scope, return the first advertised option.
+ * Reject with Error when the request offers none of these grants.
+ *
+ * Opt in through ClientOptions.interactions.approval, as createReviewClient and
+ * createRefactorClient do. The returned promise completes when the answer is selected.
+ * Session.startInteractionHandler invokes the registered policy and awaits native delivery
+ * separately. If selection rejects while the signal is active, Session attempts cancellation.
+ */
+export declare function approveWithNarrowestScope(request: Extract<InteractionRequested, {
+    kind: 'approval';
+}>): Promise<Extract<InteractionResponse, {
+    kind: 'approval';
+}>>;

package/src/lifecycle/approval.js

@@ -0,0 +1,18 @@
+/**
+ * Select an advertised grant for unattended approval. Prefer allow-once, then session, then
+ * rule grants. When several options have the same scope, return the first advertised option.
+ * Reject with Error when the request offers none of these grants.
+ *
+ * Opt in through ClientOptions.interactions.approval, as createReviewClient and
+ * createRefactorClient do. The returned promise completes when the answer is selected.
+ * Session.startInteractionHandler invokes the registered policy and awaits native delivery
+ * separately. If selection rejects while the signal is active, Session attempts cancellation.
+ */
+export async function approveWithNarrowestScope(request) {
+    const allow = request.options.find(option => option.semantic === 'allowOnce')
+        ?? request.options.find(option => option.semantic === 'allowSession')
+        ?? request.options.find(option => option.semantic === 'allowWithRule');
+    if (!allow)
+        throw new Error('Approval request has no allow option');
+    return { kind: 'approval', optionId: allow.id };
+}

package/src/lifecycle/deferred.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Create a package-internal promise with caller-owned settlement. Session uses it for observation
+ * closure, retained execution results and submission binding. A preinstalled rejection observer
+ * allows callers to attach later and still receive the original rejection.
+ */
+export declare function deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (cause: unknown) => void;
+};

package/src/lifecycle/deferred.js

@@ -0,0 +1,12 @@
+/**
+ * Create a package-internal promise with caller-owned settlement. Session uses it for observation
+ * closure, retained execution results and submission binding. A preinstalled rejection observer
+ * allows callers to attach later and still receive the original rejection.
+ */
+export function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+}

package/src/lifecycle/errors.d.ts

@@ -0,0 +1,18 @@
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Construct the package-internal error used to reject unfinished Turn results and streams.
+ * Session.finishClose passes native stop confirmation; Session.dispose uses the unconfirmed default.
+ * Even confirmed stop supplies no terminal result, so outcomeUnknown stays true. Callers still own
+ * interaction cancellation and backend release; constructing this error performs neither.
+ */
+export declare function observationClosed({ executionStopped }?: {
+    executionStopped?: 'confirmed' | 'unconfirmed';
+}): HarnessSdkError;
+/**
+ * Construct a package-internal aggregate of cleanup failures without releasing resources.
+ * Client.dispose and Session.finishClose throw this after their release attempts. The client's
+ * rethrowAfterCleanup uses it when setup and cleanup both fail. Deduplicate input causes and
+ * flatten nested release diagnostics in order. The returned error contains codes and unknown-outcome
+ * flags so raw failure messages stay out of aggregate diagnostics.
+ */
+export declare function combined(causes: unknown[]): HarnessSdkError;

package/src/lifecycle/errors.js

@@ -0,0 +1,45 @@
+import { HarnessSdkError, sdkError } from "../errors.js";
+/**
+ * Construct the package-internal error used to reject unfinished Turn results and streams.
+ * Session.finishClose passes native stop confirmation; Session.dispose uses the unconfirmed default.
+ * Even confirmed stop supplies no terminal result, so outcomeUnknown stays true. Callers still own
+ * interaction cancellation and backend release; constructing this error performs neither.
+ */
+export function observationClosed({ executionStopped = 'unconfirmed' } = {}) {
+    const message = executionStopped === 'confirmed'
+        ? 'Observation closed before a native terminal result'
+        : 'Observation closed; execution stop is unconfirmed';
+    return new HarnessSdkError('OBSERVATION_CLOSED', message, false, true, { source: 'sdk', executionStopped });
+}
+/**
+ * Construct a package-internal aggregate of cleanup failures without releasing resources.
+ * Client.dispose and Session.finishClose throw this after their release attempts. The client's
+ * rethrowAfterCleanup uses it when setup and cleanup both fail. Deduplicate input causes and
+ * flatten nested release diagnostics in order. The returned error contains codes and unknown-outcome
+ * flags so raw failure messages stay out of aggregate diagnostics.
+ */
+export function combined(causes) {
+    const errors = [...new Set(causes)].flatMap(releaseDiagnostics);
+    return new HarnessSdkError('RESOURCE_RELEASE_FAILED', 'One or more owned resources could not be released', false, true, { source: 'sdk', errors });
+}
+/**
+ * releaseDiagnostics filters nested aggregates with this guard before copying their codes. Accept
+ * only bounded machine-readable codes; do not trust nested messages or arbitrary error details.
+ */
+function isReleaseDiagnostic(value) {
+    return !!value && typeof value === 'object' && 'code' in value
+        && typeof value.code === 'string' && /^[A-Z][A-Z0-9_]{0,80}$/.test(value.code);
+}
+/**
+ * combined flat-maps each distinct cause through this normalization. Flatten an existing release
+ * aggregate or return one safe code/unknown flag, preserving input order and discarding raw causes.
+ * No cleanup is attempted; callers decide when to throw the aggregate.
+ */
+function releaseDiagnostics(cause) {
+    const error = sdkError(cause);
+    if (error.code === 'RESOURCE_RELEASE_FAILED' && Array.isArray(error.details?.errors)) {
+        return error.details.errors.filter(isReleaseDiagnostic)
+            .map(value => ({ code: value.code, outcomeUnknown: value.outcomeUnknown === true }));
+    }
+    return [{ code: error.code, outcomeUnknown: error.outcomeUnknown }];
+}

package/src/lifecycle/events.d.ts

@@ -0,0 +1,35 @@
+import type { EventSubscriptionOptions } from "../types.js";
+/**
+ * Package-internal fan-out for bounded live subscriptions without replay or producer backpressure.
+ * Session.publish feeds the session hub and Session.retainEvent feeds each execution hub.
+ * Session orders and ends those streams. Consumers release their own subscriptions.
+ */
+export declare class EventHub<T> {
+    /**
+     * Subscribe to future events with an independent queue. Session.events and Turn.events return
+     * this iterator to host consumers, who exhaust or return it, or abort the signal to release it.
+     * Invalid budgets throw synchronously. The optional filter defaults to accepting all events. An
+     * overlapping blocked read rejects with CONCURRENT_EVENT_READ and ends the subscription.
+     * Cancelling a live subscription completes its blocked and future reads and skips any
+     * buffered events. Once detached by termination or failure, abort no longer affects the reader.
+     * Late subscribers observe the stored termination even if their signal is already aborted.
+     */
+    subscribe(options?: EventSubscriptionOptions, accepts?: (value: T) => boolean): AsyncIterableIterator<T>;
+    /**
+     * Session.publish sends session events here; Session.retainEvent sends execution events here before
+     * ending terminal streams. Offer the event synchronously to each subscriber in registration
+     * order. Each subscriber filters and clones it independently. A filter, clone or queue admission
+     * failure closes that subscription and lets delivery continue. Ignore publication after hub end.
+     */
+    publish(value: T): void;
+    /**
+     * Session.retainEvent ends terminal execution streams; Session.endObservation ends remaining
+     * execution and session streams with a failure. Idempotently end all observers with an optional read
+     * failure and remove their abort listeners. Queued events drain before a truthy cause rejects reads
+     * (otherwise reads complete). Later subscribers observe the first termination without replay.
+     * Consumers still own returning or exhausting their readers.
+     */
+    end(cause?: unknown): void;
+    private readonly subscribers;
+    private termination?;
+}

package/src/lifecycle/events.js

@@ -0,0 +1,141 @@
+// Owns isolated live event fan-out and each observer's queue, reader and cancellation lifetime.
+import { BoundedEventQueue } from "../queue.js";
+/**
+ * Package-internal fan-out for bounded live subscriptions without replay or producer backpressure.
+ * Session.publish feeds the session hub and Session.retainEvent feeds each execution hub.
+ * Session orders and ends those streams. Consumers release their own subscriptions.
+ */
+export class EventHub {
+    /**
+     * Subscribe to future events with an independent queue. Session.events and Turn.events return
+     * this iterator to host consumers, who exhaust or return it, or abort the signal to release it.
+     * Invalid budgets throw synchronously. The optional filter defaults to accepting all events. An
+     * overlapping blocked read rejects with CONCURRENT_EVENT_READ and ends the subscription.
+     * Cancelling a live subscription completes its blocked and future reads and skips any
+     * buffered events. Once detached by termination or failure, abort no longer affects the reader.
+     * Late subscribers observe the stored termination even if their signal is already aborted.
+     */
+    subscribe(options = {}, accepts = () => true) {
+        const subscription = createSubscription({ options, accepts, remove: observer => this.subscribers.delete(observer) });
+        if (this.termination) {
+            subscription.queue.end(this.termination.cause);
+        }
+        else if (options.signal?.aborted) {
+            subscription.cancel();
+        }
+        else {
+            this.subscribers.add(subscription);
+            options.signal?.addEventListener('abort', subscription.cancel, { once: true });
+        }
+        return subscription.iterator;
+    }
+    /**
+     * Session.publish sends session events here; Session.retainEvent sends execution events here before
+     * ending terminal streams. Offer the event synchronously to each subscriber in registration
+     * order. Each subscriber filters and clones it independently. A filter, clone or queue admission
+     * failure closes that subscription and lets delivery continue. Ignore publication after hub end.
+     */
+    publish(value) {
+        if (this.termination)
+            return;
+        for (const subscriber of this.subscribers)
+            deliverToSubscriber(subscriber, value);
+    }
+    /**
+     * Session.retainEvent ends terminal execution streams; Session.endObservation ends remaining
+     * execution and session streams with a failure. Idempotently end all observers with an optional read
+     * failure and remove their abort listeners. Queued events drain before a truthy cause rejects reads
+     * (otherwise reads complete). Later subscribers observe the first termination without replay.
+     * Consumers still own returning or exhausting their readers.
+     */
+    end(cause) {
+        if (this.termination)
+            return;
+        this.termination = { cause };
+        for (const subscriber of this.subscribers) {
+            subscriber.end(cause);
+        }
+    }
+    subscribers = new Set();
+    termination;
+}
+/**
+ * EventHub.subscribe allocates an observer here before deciding whether to register it or close it.
+ * Queue construction can throw before registration. Closure calls remove to release hub membership
+ * and leaves the reader available to drain. Cancellation also returns the reader to release ownership.
+ */
+function createSubscription({ options, accepts, remove }) {
+    const queue = createSubscriptionQueue(options);
+    const reader = queue[Symbol.asyncIterator]();
+    let cancelled = false;
+    /** Remove hub membership and the listener registered by subscribe, leaving the reader available to drain. */
+    const detach = () => {
+        remove(subscription);
+        options.signal?.removeEventListener('abort', cancelSubscription);
+    };
+    /** Hub termination and delivery/read failures detach before closing admission, preserving buffered drain. */
+    const endSubscription = (cause) => {
+        detach();
+        queue.end(cause);
+    };
+    /** subscribe registers this abort listener; early iterator exit also skips retained data and releases ownership. */
+    const cancelSubscription = () => {
+        cancelled = true;
+        endSubscription();
+        void reader.return?.();
+    };
+    const iterator = {
+        /** Reuse the claimed reader for for-await, without acquiring a second queue reader. */
+        [Symbol.asyncIterator]() { return this; },
+        /** Await queue delivery/termination and propagate read failures after detaching; cancellation skips retained data. */
+        async next() {
+            if (cancelled)
+                return { done: true, value: undefined };
+            try {
+                const result = await reader.next();
+                if (result.done)
+                    detach();
+                return result;
+            }
+            catch (cause) {
+                endSubscription(cause);
+                throw cause;
+            }
+        },
+        /** Early exit completes this observer's blocked reads without stopping the shared producer. */
+        async return() {
+            cancelSubscription();
+            return { done: true, value: undefined };
+        },
+        /** Release this observer before rejecting with the consumer's supplied cause. */
+        async throw(cause) {
+            cancelSubscription();
+            throw cause;
+        },
+    };
+    const subscription = { queue, accepts, end: endSubscription, cancel: cancelSubscription, iterator };
+    return subscription;
+}
+/** Allocate an observer's queue, capping individual events at 8 MiB or the smaller total byte budget. Invalid limits throw before registration. */
+function createSubscriptionQueue(options) {
+    const maxBytes = options.queue?.maxBytes ?? 16 * 1024 * 1024;
+    return new BoundedEventQueue({
+        ...options.queue,
+        maxBytes,
+        maxFrameBytes: Math.min(maxBytes, 8 * 1024 * 1024),
+    });
+}
+/**
+ * EventHub.publish offers each event here. Filter before cloning so each accepting subscriber gets
+ * its own copy. On failure, close only this subscriber and preserve its buffered events before a
+ * truthy cause rejects reads or a falsy cause completes them.
+ */
+function deliverToSubscriber(subscriber, value) {
+    try {
+        if (subscriber.accepts(value))
+            subscriber.queue.push(structuredClone(value));
+    }
+    catch (cause) {
+        subscriber.end(cause);
+    }
+}

package/src/lifecycle/execution-observation.d.ts

@@ -0,0 +1,33 @@
+import type { AhpEvent } from '@anureo/protocol';
+import type { EventHub } from "./events.js";
+import type { Input, RequestOptions, TurnResult } from "../types.js";
+/**
+ * Internal port allocated by Session.context and passed to Turn by Session.submitExecution when
+ * association resolves. Turn uses it for live subscriptions, terminal results and explicit controls.
+ * Session owns event ordering, shared settlement and native resources. Each Turn owns its wait
+ * and subscription cancellation.
+ */
+export interface ExecutionObservation {
+    /** Stable execution ID reported by the adapter and shared by submissions bound to the same turn. */
+    readonly id: string;
+    /** Session-owned live producer hub; Turn.events creates an isolated subscription without replay. */
+    readonly events: EventHub<AhpEvent>;
+    /** Session.retainEvent resolves the frozen snapshot at native completion. Session.endObservation rejects unfinished results on closure. */
+    readonly result: Promise<TurnResult>;
+    /** Session.retainEvent sets this on turn/completed before publishing the terminal event and ending its stream. */
+    readonly terminal: boolean;
+    /**
+     * Turn.steer explicitly invokes the callback installed by Session.context. It normalizes input and
+     * awaits Session.request('turn/steer') with this execution as the atomic target. It discards the
+     * validated receipt and propagates normalization, admission, dispatch and wait rejections. Native
+     * work continues if the caller ends its wait after admission.
+     */
+    steer(input: Input, wait?: RequestOptions): Promise<void>;
+    /**
+     * Turn.interrupt explicitly invokes the callback installed by Session.context. It awaits
+     * Session.request('turn/interrupt') for this execution, discarding the validated receipt or
+     * propagating admission, dispatch and wait rejections. Session.retainEvent settles result
+     * separately when the terminal event arrives.
+     */
+    interrupt(wait?: RequestOptions): Promise<void>;
+}

package/src/lifecycle/immutable.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Clone acyclic protocol data and freeze enumerable object and array descendants. Cloning or
+ * freezing failures throw and leave the original value untouched.
+ *
+ * Called by:
+ * - Client.initialize to store negotiated capabilities; failure rejects initialization.
+ * - Session's constructor/attach and binding/reference/capabilities/snapshot getters to detach stored
+ *   or exposed state. Session.executeRequest returns frozen receipts; failure rejects its request.
+ * - ResultAccumulator.finish to return a terminal snapshot. Session.retainEvent settles the shared
+ *   Turn result with that snapshot, or lets a failure propagate through ordered publication.
+ */
+export declare function immutable<T>(value: T): T;

package/src/lifecycle/immutable.js

@@ -0,0 +1,28 @@
+/**
+ * Clone acyclic protocol data and freeze enumerable object and array descendants. Cloning or
+ * freezing failures throw and leave the original value untouched.
+ *
+ * Called by:
+ * - Client.initialize to store negotiated capabilities; failure rejects initialization.
+ * - Session's constructor/attach and binding/reference/capabilities/snapshot getters to detach stored
+ *   or exposed state. Session.executeRequest returns frozen receipts; failure rejects its request.
+ * - ResultAccumulator.finish to return a terminal snapshot. Session.retainEvent settles the shared
+ *   Turn result with that snapshot, or lets a failure propagate through ordered publication.
+ */
+export function immutable(value) {
+    const copy = structuredClone(value);
+    /**
+     * immutable invokes this recursive walk on its detached clone. Freeze descendants first so no
+     * enumerable object/array child of a returned protocol snapshot remains writable; failures propagate.
+     */
+    const freeze = (entry) => {
+        if (entry && typeof entry === 'object') {
+            for (const child of Object.values(entry)) {
+                freeze(child);
+            }
+            Object.freeze(entry);
+        }
+    };
+    freeze(copy);
+    return copy;
+}

package/src/lifecycle/input.d.ts

@@ -0,0 +1,9 @@
+import type { InputBlock } from '@anureo/protocol';
+import type { Input } from "../types.js";
+/**
+ * Normalize host input into one text block for a string or a detached copy of a block array.
+ * Throw INVALID_PARAMS for other values or clone failure. Session.submit and the callback installed
+ * by Session.context for Turn.steer pass the resulting blocks to request admission, which validates
+ * their contents and capabilities. Both expose normalization failures as promise rejections.
+ */
+export declare function inputBlocks(input: Input): InputBlock[];

package/src/lifecycle/input.js

@@ -0,0 +1,19 @@
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Normalize host input into one text block for a string or a detached copy of a block array.
+ * Throw INVALID_PARAMS for other values or clone failure. Session.submit and the callback installed
+ * by Session.context for Turn.steer pass the resulting blocks to request admission, which validates
+ * their contents and capabilities. Both expose normalization failures as promise rejections.
+ */
+export function inputBlocks(input) {
+    if (typeof input === 'string')
+        return [{ type: 'text', text: input }];
+    if (!Array.isArray(input))
+        throw new HarnessSdkError('INVALID_PARAMS');
+    try {
+        return structuredClone(input);
+    }
+    catch {
+        throw new HarnessSdkError('INVALID_PARAMS');
+    }
+}