crewx-pi-kit 0.1.2 → 0.1.3

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: {}};
 }
@@ -61,6 +94,41 @@ function query(parameters: Record<string, string | number | boolean | undefined>
 }
 
 export default function crewxTools(pi: ExtensionAPI) {
+  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,6 +1,6 @@
 {
   "name": "crewx-pi-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Typed CrewX tools and operating skills for managed Pi agents.",
   "type": "module",
   "files": [

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.