crewx-pi-kit 0.1.1 → 0.1.3

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.1
+pi install npm:crewx-pi-kit@0.1.2
 ```
 
 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: {}};
 }
@@ -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",
@@ -105,7 +173,7 @@ export default function crewxTools(pi: ExtensionAPI) {
     label: "Update CrewX memory",
     description: "Update a CrewX memory originally recorded by this agent.",
     parameters: Type.Object({
-      id: Type.Integer({minimum: 1}),
+      id: Type.Union([Type.String({minLength: 1, maxLength: 128}), Type.Integer({minimum: 1})]),
       title: Type.Optional(Type.String({maxLength: 255})),
       content: Type.Optional(Type.String({maxLength: 100_000})),
       category: Type.Optional(Type.String({maxLength: 50})),
@@ -114,7 +182,7 @@ export default function crewxTools(pi: ExtensionAPI) {
       channel_id: Type.Optional(Type.Union([Type.Integer({minimum: 1}), Type.Null()])),
     }),
     async execute(_id, {id, ...body}, signal) {
-      return result(await crewxRequest(`/memories/${id}`, {method: "PATCH", body, signal}));
+      return result(await crewxRequest(`/memories/${encodeURIComponent(String(id))}`, {method: "PATCH", body, signal}));
     },
   });
 
@@ -155,7 +223,7 @@ export default function crewxTools(pi: ExtensionAPI) {
     label: "Update CrewX task",
     description: "Update a task assigned to this agent.",
     parameters: Type.Object({
-      id: Type.Integer({minimum: 1}),
+      id: Type.Union([Type.String({minLength: 1, maxLength: 128}), Type.Integer({minimum: 1})]),
       status: Type.Optional(Type.Union([
         Type.Literal("backlog"), Type.Literal("todo"), Type.Literal("in_progress"),
         Type.Literal("review"), Type.Literal("done"), Type.Literal("cancelled"),
@@ -164,7 +232,7 @@ export default function crewxTools(pi: ExtensionAPI) {
       description: Type.Optional(Type.String({maxLength: 100_000})),
     }),
     async execute(_id, {id, ...body}, signal) {
-      return result(await crewxRequest(`/tasks/${id}`, {method: "PATCH", body, signal}));
+      return result(await crewxRequest(`/tasks/${encodeURIComponent(String(id))}`, {method: "PATCH", body, signal}));
     },
   });
 
@@ -197,14 +265,14 @@ export default function crewxTools(pi: ExtensionAPI) {
     label: "Update CrewX document",
     description: "Safely update an unprotected CrewX document using its current version.",
     parameters: Type.Object({
-      id: Type.Integer({minimum: 1}),
+      id: Type.Union([Type.String({minLength: 1, maxLength: 128}), Type.Integer({minimum: 1})]),
       expected_version: Type.Integer({minimum: 1}),
       title: Type.Optional(Type.String({maxLength: 255})),
       content: Type.Optional(Type.String({maxLength: 250_000})),
       summary: Type.Optional(Type.String({maxLength: 255})),
     }),
     async execute(_id, {id, ...body}, signal) {
-      return result(await crewxRequest(`/documents/${id}`, {method: "PATCH", body, signal}));
+      return result(await crewxRequest(`/documents/${encodeURIComponent(String(id))}`, {method: "PATCH", body, signal}));
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewx-pi-kit",
-  "version": "0.1.1",
+  "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.