@aphrody/winclean 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Compatibility facade for the unified Aphrody OS kernel. */
+import { KernelClient } from "@aphrody/os";
+import { GeneratedTools, type ToolArgsMap, type ToolName } from "./generated";
+import { TOOL_CATALOG } from "./catalog";
+import { ToolResult } from "./result";
+
+export * from "./generated";
+export * from "./result";
+export { KernelError } from "@aphrody/os";
+
+export interface ToolInfo {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/** Local kernel-backed WinClean client. */
+export class Winclean extends GeneratedTools implements Disposable {
+  readonly path = "kernel://aphrody-os";
+  #clientPromise: Promise<KernelClient> | undefined;
+  #closed = false;
+
+  private constructor(readonly endpoint?: string) {
+    super();
+  }
+
+  static open(endpoint?: string): Winclean {
+    return new Winclean(endpoint);
+  }
+
+  get version(): string {
+    return "kernel";
+  }
+
+  listTools(): ToolInfo[] {
+    return TOOL_CATALOG.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema,
+    }));
+  }
+
+  async call<N extends ToolName>(name: N, args?: ToolArgsMap[N]): Promise<ToolResult>;
+  async call(name: string, args?: Record<string, unknown>): Promise<ToolResult>;
+  async call(name: string, args: object = {}): Promise<ToolResult> {
+    if (this.#closed) throw new Error("Winclean client is closed");
+    const client = await this.#client();
+    try {
+      const value = await client.call(name, args as Record<string, any>);
+      return new ToolResult(name, {
+        structuredContent: value,
+        content: [{ type: "text", text: JSON.stringify(value) }],
+      });
+    } catch (error) {
+      const text = error instanceof Error ? error.message : String(error);
+      return new ToolResult(name, { isError: true, content: [{ type: "text", text }] });
+    }
+  }
+
+  /** Synchronous calls are routed through the kernel RPC client. */
+  callSync(_name: string, _args?: Record<string, unknown>): ToolResult {
+    throw new Error(
+      "callSync is unavailable: use await Winclean.open().call(...) through the Aphrody OS kernel",
+    );
+  }
+
+  close(): void {
+    this.#closed = true;
+    void this.#clientPromise?.then((client) => client.close());
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
+  async #client(): Promise<KernelClient> {
+    return (this.#clientPromise ??= KernelClient.connect(this.endpoint, "bun/winclean"));
+  }
+}

package/src/result.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+/** One MCP content block. */
+export type Content =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | { type: "audio"; data: string; mimeType: string }
+  | { type: string; [key: string]: unknown };
+
+/** Raw MCP `CallToolResult` as returned by `winclean_call`. */
+export interface RawToolResult {
+  content?: Content[];
+  structuredContent?: unknown;
+  isError?: boolean;
+}
+
+/** Thrown by {@link ToolResult.ok} / {@link ToolResult.json} when a tool reports `isError`. */
+export class ToolError extends Error {
+  constructor(
+    readonly tool: string,
+    readonly result: ToolResult,
+  ) {
+    super(`${tool}: ${result.text}`);
+    this.name = "ToolError";
+  }
+}
+
+/** Result of a WinClean tool invocation. */
+export class ToolResult {
+  readonly content: Content[];
+  readonly structuredContent: unknown;
+  readonly isError: boolean;
+
+  constructor(
+    readonly tool: string,
+    raw: RawToolResult,
+  ) {
+    this.content = raw.content ?? [];
+    this.structuredContent = raw.structuredContent;
+    this.isError = raw.isError === true;
+  }
+
+  /** Concatenated text blocks. */
+  get text(): string {
+    return this.content
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
+      .map((c) => c.text)
+      .join("\n");
+  }
+
+  /** Decoded image blocks (PNG frames from `computer_observe`, `window_capture`, …). */
+  get images(): { mimeType: string; bytes: Uint8Array }[] {
+    return this.content
+      .filter((c): c is { type: "image"; data: string; mimeType: string } => c.type === "image")
+      .map((c) => ({
+        mimeType: c.mimeType,
+        bytes: Uint8Array.from(Buffer.from(c.data, "base64")),
+      }));
+  }
+
+  /** Throws {@link ToolError} when the tool failed; returns `this` otherwise. */
+  ok(): this {
+    if (this.isError) throw new ToolError(this.tool, this);
+    return this;
+  }
+
+  /** `structuredContent`, or the first text block parsed as JSON. Throws on tool error. */
+  json<T = any>(): T {
+    this.ok();
+    if (this.structuredContent !== undefined) return this.structuredContent as T;
+    const first = this.content.find((c): c is { type: "text"; text: string } => c.type === "text");
+    return JSON.parse(first?.text ?? "null") as T;
+  }
+}