crewx-pi-kit 0.1.2 → 0.1.4

package/README.md

@@ -10,7 +10,7 @@ work, safety boundaries, and agent handoffs.
 Install it with Pi:
 
 ```sh
-pi install npm:crewx-pi-kit@0.1.2
+pi install npm:crewx-pi-kit@0.1.4
 ```
 
 CrewX injects short-lived `CREWX_URL` and `CREWX_TOKEN` capabilities only while

package/extensions/crewx-tools.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
 
 const API_PATH = "/api/agent/v1";
 const MAX_RESULT_CHARS = 100_000;
@@ -48,6 +50,37 @@ async function crewxRequest(
   return payload;
 }
 
+async function crewxUpload(
+  path: string,
+  caption: string | undefined,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const { baseUrl, token } = connection();
+  const contents = await readFile(path);
+  const form = new FormData();
+  form.set("file", new Blob([contents]), basename(path));
+  if (caption?.trim()) form.set("caption", caption.trim());
+  const response = await fetch(`${baseUrl}${API_PATH}/files`, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${token}`,
+    },
+    body: form,
+    redirect: "error",
+    ...(signal ? { signal } : {}),
+  });
+  const payload = (await response.json().catch(() => ({
+    message: `CrewX returned HTTP ${response.status}.`,
+  }))) as JsonRecord;
+  if (!response.ok) {
+    throw new Error(typeof payload.message === "string"
+      ? payload.message
+      : `CrewX returned HTTP ${response.status}.`);
+  }
+  return payload;
+}
+
 function result(value: unknown) {
   return {content: [{type: "text" as const, text: jsonText(value)}], details: {}};
 }
@@ -60,7 +93,132 @@ function query(parameters: Record<string, string | number | boolean | undefined>
   return search.size ? `?${search.toString()}` : "";
 }
 
+function wait(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("CrewX handover was cancelled."));
+      return;
+    }
+
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new Error("CrewX handover was cancelled."));
+    }, {once: true});
+  });
+}
+
 export default function crewxTools(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "crewx_request_handover",
+    label: "Request user computer handover",
+    description: "Pause the current browser task and ask a CrewX user to take control of this agent's computer. This tool waits until the user gives control back, then returns so work can resume.",
+    parameters: Type.Object({
+      reason: Type.String({
+        minLength: 1,
+        maxLength: 1000,
+        description: "A short, user-facing explanation of why human input is required.",
+      }),
+      kind: Type.Optional(Type.Union([
+        Type.Literal("authentication"),
+        Type.Literal("verification"),
+        Type.Literal("captcha"),
+        Type.Literal("payment"),
+        Type.Literal("approval"),
+        Type.Literal("other"),
+      ])),
+      instructions: Type.Optional(Type.String({
+        maxLength: 2000,
+        description: "The exact action the user should complete before giving control back.",
+      })),
+      url: Type.Optional(Type.String({
+        maxLength: 2048,
+        description: "The current HTTP(S) page where the user is needed.",
+      })),
+    }),
+    promptSnippet: "Hand browser control to a CrewX user when a human-only step blocks progress.",
+    promptGuidelines: [
+      "Use crewx_request_handover for sign-in, 2FA, CAPTCHA, consent, payment, approval, or any other step that requires a person to interact with the live computer.",
+      "Before calling it, navigate to the exact blocked screen and explain the one action the user must complete.",
+      "Never ask for passwords, one-time codes, payment details, or other secrets in chat. Stop browser actions while this tool is waiting.",
+      "When the tool returns completed, verify the page state and continue the original task from the same point.",
+    ],
+    async execute(_id, params, signal) {
+      const created = await crewxRequest("/handovers", {
+        method: "POST",
+        body: params,
+        signal,
+      }) as {handover?: {id?: unknown}};
+      const handoverId = created.handover?.id;
+      if (typeof handoverId !== "string" || handoverId.length === 0) {
+        throw new Error("CrewX created a handover without returning its ID.");
+      }
+
+      while (true) {
+        await wait(2_000, signal);
+        const current = await crewxRequest(
+          `/handovers/${encodeURIComponent(handoverId)}`,
+          {signal},
+        ) as {handover?: {status?: unknown}};
+        const status = current.handover?.status;
+
+        if (status === "ended") {
+          return result({
+            handover: {id: handoverId, status: "completed"},
+            instruction: "The user gave control back. Verify the current screen, then continue the original task.",
+          });
+        }
+        if (status === "expired") {
+          return result({
+            handover: {id: handoverId, status: "expired"},
+            instruction: "The user did not complete the handover before it expired. Explain the blocker and stop browser actions.",
+          });
+        }
+        if (status !== "requested" && status !== "active") {
+          return result({
+            handover: {id: handoverId, status},
+            instruction: "The handover ended without a completed return of control. Re-check the task before taking any browser action.",
+          });
+        }
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "crewx_attach_file",
+    label: "Attach CrewX file",
+    description: "Upload a durable file and attach it to the current CrewX reply.",
+    parameters: Type.Object({
+      path: Type.String({minLength: 1, maxLength: 4096}),
+      caption: Type.Optional(Type.String({maxLength: 1000})),
+    }),
+    promptSnippet: "Deliver generated files directly into the CrewX conversation.",
+    promptGuidelines: [
+      "Use crewx_attach_file for requested screenshots, reports, exports, and other deliverables instead of returning a local path.",
+    ],
+    async execute(_id, params, signal) {
+      return result(await crewxUpload(params.path, params.caption, signal));
+    },
+  });
+
+  pi.registerTool({
+    name: "crewx_publish_preview",
+    label: "Publish CrewX preview",
+    description: "Publish a web service running on this CrewX Cloud Agent as a live preview.",
+    parameters: Type.Object({
+      port: Type.Integer({minimum: 1024, maximum: 65535}),
+      title: Type.Optional(Type.String({maxLength: 120})),
+    }),
+    promptSnippet: "Share interactive work as a managed CrewX live preview.",
+    promptGuidelines: [
+      "Bind the service to 0.0.0.0, verify it locally, then publish the port.",
+      "Do not reveal provider URLs, access tokens, or local file paths in the reply.",
+    ],
+    async execute(_id, params, signal) {
+      return result(await crewxRequest("/previews", {method: "POST", body: params, signal}));
+    },
+  });
+
   pi.registerTool({
     name: "crewx_memory_search",
     label: "Search CrewX memory",

package/package.json

@@ -1,19 +1,16 @@
 {
   "name": "crewx-pi-kit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Typed CrewX tools and operating skills for managed Pi agents.",
   "type": "module",
-  "files": [
-    "extensions",
-    "skills"
-  ],
+  "files": ["extensions", "skills"],
   "pi": {
-    "extensions": [
-      "extensions"
-    ],
-    "skills": [
-      "skills"
-    ]
+    "extensions": ["extensions"],
+    "skills": ["skills"]
+  },
+  "scripts": {
+    "types:check": "tsc --noEmit",
+    "test": "tsc --noEmit"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -25,15 +22,7 @@
     "typebox": "^1.0.55",
     "typescript": "^5.9.3"
   },
-  "engines": {
-    "node": ">=22"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "scripts": {
-    "types:check": "tsc --noEmit",
-    "test": "tsc --noEmit"
-  }
-}
+  "engines": {"node": ">=22"},
+  "publishConfig": {"access": "public"},
+  "license": "MIT"
+}

package/skills/artifact-delivery/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: artifact-delivery
+description: Deliver files and interactive previews back to the CrewX conversation. Use when an assignment produces screenshots, reports, exports, generated media, or a locally running web experience.
+---
+
+# Artifact Delivery
+
+1. Treat the final CrewX reply as the handoff, not the machine filesystem. Never ask a teammate to retrieve `/home`, `/tmp`, or another local path.
+2. Use `crewx_attach_file` for durable outputs such as screenshots, documents, archives, data exports, and generated media. Add a short caption that explains what the file contains.
+3. Use `crewx_publish_preview` only when interaction materially improves the handoff. Bind the service to `0.0.0.0`, verify the local port, then publish it.
+4. A preview is a running service, not permanent storage. Also attach durable source or output files when the teammate may need them later.
+5. Do not include provider URLs, preview tokens, credentials, or local paths in the response. CrewX presents the safe file and preview controls automatically.
+6. Confirm that every requested deliverable was attached before sending the concise final response.

package/skills/human-computer-handover/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: human-computer-handover
+description: Ask a CrewX user to take control of the managed computer when a website requires authentication, verification, approval, or another human-only action.
+---
+
+# Human computer handover
+
+Use `crewx_request_handover` when browser or desktop work reaches a step that a person must complete, including sign-in, two-factor authentication, CAPTCHA, consent, payment confirmation, or sensitive approval.
+
+Before requesting handover:
+
+1. Navigate to the exact screen where human input is required.
+2. Explain the visible blocker and the single action the user should complete.
+3. Never request credentials, one-time codes, payment details, cookies, or tokens in chat.
+
+While the tool is waiting, stop all browser and desktop actions. The user has control of the same machine.
+
+After the tool reports that control was returned, inspect the current screen, verify that the human-only step succeeded, and continue the original task from that state.

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 CrewX contributors
-
-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.