@falari/harness 0.0.0-stage → 0.8.9

package/lib/tools.js

@@ -0,0 +1,193 @@
+/**
+ * Agent tools. Every tool calls FalariDataService, which is the same object the
+ * Web routes use — one operation, two callers.
+ */
+import { ServiceError } from './errors.js';
+
+/** Stop `wait: true` here so a tool call stays well inside the call timeout. */
+const WAIT_LIMIT_MS = 120_000;
+const WAIT_POLL_MS = 1500;
+
+const TERMINAL = new Set(['completed', 'terminated', 'failed', 'needs_source']);
+const ACTIVE = new Set(['creating', 'queued', 'uploading', 'paused']);
+
+function text(value) {
+  return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+
+function sleep(ms) {
+  return new Promise((done) => setTimeout(done, ms));
+}
+
+const output = {
+  schema: { type: 'object', additionalProperties: true },
+  render(_args, value) {
+    return text(value);
+  },
+};
+
+export function registerTools(ctx, service) {
+  ctx.tools.register({
+    name: 'falari_status',
+    description:
+      'Show the Falari Agent Key status: configured state, agent address, permission tiers, allowance, balance, expiry and network. Call this before any Falari upload or download. When no key is configured, tell the user to open the plugin page: Plugins → Falari Data → Configure.',
+    parameters: {
+      type: 'object',
+      properties: {
+        refresh: { type: 'boolean', description: 'Read the chain instead of the cached status.' },
+      },
+      additionalProperties: false,
+    },
+    output,
+    execute: async (args) => service.keyStatus({ refresh: Boolean(args && args.refresh) }),
+  });
+
+  ctx.tools.register({
+    name: 'falari_quote',
+    description:
+      'Price a Falari upload before spending anything. Give either `path` (a file inside the session working directory) or `size_bytes`. Returns the escrow deposit, service fees, the total, and whether the Agent Key allowance and owner balance cover it.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path inside the session working directory.' },
+        size_bytes: { type: 'number', description: 'File size in bytes when there is no local file.' },
+        duration: {
+          type: 'string',
+          description: 'Storage duration: permanent, 30d, 90d, 1y, 5y, 10y, or a number of seconds.',
+        },
+      },
+      additionalProperties: false,
+    },
+    output,
+    execute: async (args, exec) => {
+      const input = args && typeof args === 'object' ? args : {};
+      let size = Number(input.size_bytes);
+      if (!Number.isFinite(size) || size <= 0) {
+        if (!input.path) {
+          throw new ServiceError('missing_size', 'Pass either path or size_bytes to price an upload.');
+        }
+        const target = await service.guardedSourcePath(exec.agent, input.path);
+        const info = await service.assertUploadableFile(target);
+        size = info.size;
+      }
+      return service.quote({ sizeBytes: size, duration: input.duration });
+    },
+  });
+
+  ctx.tools.register({
+    name: 'falari_upload',
+    description:
+      'Upload a local file to Falari storage with the configured Agent Key. The path must stay inside the session working directory. Uploading spends FAR: call falari_quote first when the user cares about cost. Returns a task; with wait=true it waits up to two minutes and otherwise reports the task so falari_task can be polled.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path inside the session working directory.' },
+        privacy: { type: 'string', enum: ['public', 'private'], description: 'Encrypt client-side (private) or upload plaintext (public).' },
+        duration: {
+          type: 'string',
+          description: 'Storage duration: permanent, 30d, 90d, 1y, 5y, 10y, or a number of seconds.',
+        },
+        file_name: { type: 'string', description: 'Name recorded on chain; defaults to the file name.' },
+        wait: { type: 'boolean', description: 'Wait (up to 2 minutes) for the upload to finish before returning.' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    output,
+    execute: async (args, exec) => {
+      const input = args && typeof args === 'object' ? args : {};
+      const target = await service.guardedSourcePath(exec.agent, input.path);
+      let task = await service.enqueueUpload({
+        path: target,
+        privacy: input.privacy,
+        duration: input.duration,
+        fileName: input.file_name,
+      });
+      if (input.wait !== true) return task;
+      const deadline = Date.now() + WAIT_LIMIT_MS;
+      while (!TERMINAL.has(task.status) && Date.now() < deadline) {
+        await sleep(WAIT_POLL_MS);
+        try {
+          task = await service.getTask(task.id);
+        } catch {
+          break;
+        }
+      }
+      return { ...task, timedOut: !TERMINAL.has(task.status) };
+    },
+  });
+
+  ctx.tools.register({
+    name: 'falari_task',
+    description:
+      'Read Falari upload tasks: pass task_id for one task, or omit it for the recent list. Use this to follow an upload started with wait=false.',
+    parameters: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task id returned by falari_upload.' },
+        active_only: { type: 'boolean', description: 'Only return tasks that are still running or paused.' },
+      },
+      additionalProperties: false,
+    },
+    output,
+    execute: async (args) => {
+      const input = args && typeof args === 'object' ? args : {};
+      if (input.task_id) return service.getTask(String(input.task_id));
+      const tasks = await service.listTasks();
+      return input.active_only === true ? tasks.filter((task) => ACTIVE.has(task.status)) : tasks;
+    },
+  });
+
+  ctx.tools.register({
+    name: 'falari_list',
+    description:
+      "List this account's Falari intents (uploaded files and their deal state), newest first. Read-only: listing needs no key tier.",
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'How many intents to return (default 50, max 200).' },
+      },
+      additionalProperties: false,
+    },
+    output,
+    execute: async (args) => {
+      const input = args && typeof args === 'object' ? args : {};
+      return service.listIntents({ limit: Number(input.limit) || 50 });
+    },
+  });
+
+  ctx.tools.register({
+    name: 'falari_download',
+    description:
+      'Download one Falari intent to disk, verify its roots and decrypt it when private. Public data needs no key; private data needs the Data Key or an Agent Key whose data grant covers the intent. Waits up to two minutes, then returns the task so falari_task can be polled.',
+    parameters: {
+      type: 'object',
+      properties: {
+        intent_id: { type: 'string', description: 'Intent id, for example intent_<hex>.' },
+        data_key: { type: 'string', description: 'Base64 32-byte Data Key, needed when this key cannot unwrap the intent.' },
+        out_path: { type: 'string', description: 'File name or path inside the download directory.' },
+      },
+      required: ['intent_id'],
+      additionalProperties: false,
+    },
+    output,
+    execute: async (args) => {
+      const input = args && typeof args === 'object' ? args : {};
+      let task = await service.startDownload({
+        intentId: input.intent_id,
+        dataKey: input.data_key,
+        outPath: input.out_path,
+      });
+      const deadline = Date.now() + WAIT_LIMIT_MS;
+      while ((task.status === 'running' || task.status === 'queued') && Date.now() < deadline) {
+        await sleep(WAIT_POLL_MS);
+        try {
+          task = await service.getTask(task.id);
+        } catch {
+          break;
+        }
+      }
+      return { ...task, timedOut: task.status === 'running' || task.status === 'queued' };
+    },
+  });
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Falari Data / Falari 数据",
+    "description": "Upload files to Falari storage and download them back inside DeepSeek Harness, with an Agent Key as the only credential. 在 DeepSeek Harness 内使用 Falari 存储：用 Agent Key 上传文件、按 intent 下载并解密数据。"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Falari 数据 / Falari Data",
+    "description": "在 DeepSeek Harness 内使用 Falari 存储：用 Agent Key 上传文件、按 intent 下载并解密数据。 Upload files to Falari storage and download them back inside DeepSeek Harness, with an Agent Key as the only credential."
+  }
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@falari/harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.9",
+  "description": "Falari Data client for DeepSeek Harness: Agent Key status, data upload and download.",
+  "license": "MIT",
+  "author": "Falari",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/falarichain/harness.git"
+  },
+  "homepage": "https://github.com/falarichain/harness",
+  "bugs": {
+    "url": "https://github.com/falarichain/harness/issues"
+  },
+  "keywords": [
+    "falari",
+    "harness",
+    "dsh",
+    "storage",
+    "agent-key"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.png"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib/*.js",
+    "lib/falari-sdk.cjs",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.png",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:sdk": "bash scripts/build-sdk.sh",
+    "test:unit": "node scripts/unit-host.mjs && node scripts/unit-pin.mjs && node scripts/unit-vault.mjs",
+    "test:host": "node scripts/smoke-host.mjs",
+    "test:client": "node scripts/smoke-client.mjs",
+    "test": "node scripts/unit-host.mjs && node scripts/unit-pin.mjs && node scripts/unit-vault.mjs && node scripts/smoke-host.mjs && node scripts/smoke-client.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}