@pi-oxide/extension-js 0.12.4 → 0.13.0

package/shared/registry/manifest.d.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+export interface Command {
+    action: string;
+    params: unknown;
+    call_id?: number;
+    runId?: string;
+}
+export type AsyncError = {
+    message: string;
+    code: string;
+    category?: string;
+    hint?: string;
+    recovery?: string[];
+    details?: Record<string, unknown>;
+};
+export type AsyncResponse<T = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AsyncError;
+};
+export interface ToolDocParam {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+}
+export interface ToolDoc {
+    action: string;
+    namespace: string;
+    description: string;
+    params: ToolDocParam[];
+    returns: {
+        type: string;
+        description: string;
+    };
+    errorCode: string;
+    errorCategory?: string;
+    example?: string;
+}
+export type ToolAgentMeta = {
+    prerequisites?: string[];
+    notes?: string[];
+    tags?: Array<"read" | "write" | "mutation" | "snapshot" | "navigation" | "chrome">;
+    relatedApis?: string[];
+};
+export interface ToolDefinition<P, R> {
+    action: string;
+    namespace: string;
+    description: string;
+    params: z.ZodSchema<P>;
+    returns: z.ZodSchema<R>;
+    handler: (params: P, callId?: number, runId?: string, signal?: AbortSignal) => Promise<R>;
+    paramTypes: ToolDocParam[];
+    returnType?: string;
+    returnDoc: string;
+    errorCode: string;
+    errorCategory?: string;
+    example?: string;
+}
+export type ExecutionContextId = string;
+export type CallContext = {
+    action: string;
+    callId?: number;
+    runId?: string;
+    signal?: AbortSignal;
+};
+export type JsCallSpec<P, R> = {
+    action: string;
+    namespace: string;
+    name: string;
+    description: string;
+    params: z.ZodSchema<P>;
+    returns: z.ZodSchema<R>;
+    fields?: string[];
+    aliases?: Array<{
+        namespace: string;
+        name: string;
+        fields?: string[];
+    }>;
+    owner: ExecutionContextId;
+    handler: (params: P, ctx: CallContext) => Promise<R>;
+    errorCode: string;
+    errorCategory?: string;
+    paramTypes?: ToolDocParam[];
+    returnType?: string;
+    returnDoc?: string;
+    /** Chrome permission required to use this API (e.g. "notifications", "cookies"). */
+    permission?: string;
+    /** Runnable example string for this API. */
+    example?: string;
+    /** Agent-facing metadata for this API. */
+    agentMeta?: ToolAgentMeta;
+};
+export type SerializableJsCallManifestEntry = {
+    action: string;
+    namespace: string;
+    name: string;
+    publicName: string;
+    description: string;
+    fields: string[] | null;
+    aliases: Array<{
+        namespace: string;
+        name: string;
+        fields: string[] | null;
+    }> | null;
+    owner: ExecutionContextId;
+    paramsDoc: ToolDocParam[];
+    returnsDoc: {
+        type: string;
+        description: string;
+    };
+    errorCode: string;
+    errorCategory?: string;
+    /** Chrome permission required to use this API (e.g. "notifications", "cookies"). */
+    permission?: string;
+    /** Runnable example string for this API. */
+    example?: string;
+    prerequisites?: string[];
+    notes?: string[];
+    tags?: string[];
+    relatedApis?: string[];
+};
+/** Rust/WASM often passes BTreeMap params as a JS Map; Zod object schemas need plain objects.
+ *  Native-parity chrome actions also JSON-round-trip in dispatch_handler; this covers relay paths. */
+export declare function coerceWasmParams(params: unknown): unknown;
+/** Convert a serializable manifest entry to the shape expected by WASM registerJsCall/registerJsCallBatch. */
+export declare function manifestEntryToWasm(entry: SerializableJsCallManifestEntry): Record<string, unknown>;

package/shared/registry/normalize-agent-error.d.ts

@@ -0,0 +1,17 @@
+import { contentScriptMissingError, isContentScriptConnectionError, labelNotFoundError, noTabError, notInteractableError, observationRequiredError, StaleRefCandidate, staleRefError, throwStructuredAgentError } from './agent-errors.js';
+import { AsyncError } from './manifest.js';
+
+export { contentScriptMissingError, isContentScriptConnectionError, labelNotFoundError, noTabError, notInteractableError, observationRequiredError, type StaleRefCandidate, staleRefError, throwStructuredAgentError, };
+export declare function normalizeAgentError(err: unknown, context?: {
+    tabId?: number;
+    url?: string;
+    action?: string;
+}): AsyncError;
+export declare function agentErrorResponse(err: unknown, context?: {
+    tabId?: number;
+    url?: string;
+    action?: string;
+}): {
+    ok: false;
+    error: AsyncError;
+};

package/shared/registry/routes.d.ts

@@ -0,0 +1,14 @@
+import { ExecutionContextId } from './manifest.js';
+import { Route, TabPolicy } from './types.js';
+
+export declare function setRoute(action: string, route: Route): void;
+export declare function getRoute(action: string): Route | undefined;
+export declare function clearRoutes(): void;
+export declare function inferTabPolicy(action: string): TabPolicy;
+export declare function inferEndpoint(owner: ExecutionContextId): Route["endpoint"];
+export declare function inferOwner(action: string, owner: ExecutionContextId): ExecutionContextId;
+export declare function routeFromOwner(action: string, owner: ExecutionContextId): Route;
+export declare function populateRoutesFromManifest(entries: Array<{
+    action: string;
+    owner: ExecutionContextId;
+}>): void;

package/shared/registry/types.d.ts

@@ -0,0 +1,12 @@
+export type TabPolicy = "active" | "required" | "optional";
+export type RouteEndpoint = "main-thread" | "content-script" | `worker:${string}`;
+export type Route = {
+    endpoint: RouteEndpoint;
+    tabPolicy: TabPolicy;
+};
+export type DispatchContext = {
+    action: string;
+    callId?: number;
+    runId?: string;
+    signal?: AbortSignal;
+};

package/shared/registry/zod-to-docs.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { ToolDocParam } from './manifest.js';
+
+/**
+ * Produce a human-readable type description for a Zod schema.
+ *
+ * @param schema   – the Zod schema to describe
+ * @param depth    – current recursion depth (used internally)
+ * @param maxDepth – maximum depth before truncating nested objects with "...";
+ *                   default 2 is used for validation-error messages, 3 for docs
+ */
+export declare function describeSchema(schema: z.ZodTypeAny, depth?: number, maxDepth?: number): string;
+/**
+ * Derive parameter documentation from a ZodObject schema.
+ *
+ * Transparent wrappers (ZodEffects, ZodDefault, ZodPipeline) are unwrapped
+ * before inspecting the shape. Keys starting with `__` are filtered out as
+ * internal convention. ZodDefault fields are treated as optional because the
+ * default value means agents don't need to provide them.
+ */
+export declare function zodToParamDocs(schema: z.ZodTypeAny): ToolDocParam[];
+/**
+ * Derive a rich return-type string from a Zod schema.
+ *
+ * Uses describeSchema with maxDepth=3 so nested objects are expanded one level
+ * deeper than validation-error messages.
+ */
+export declare function zodToReturnType(schema: z.ZodTypeAny): string;