@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/src/setup-autostart.mjs

@@ -0,0 +1,197 @@
+import { walletCliPath } from "./wallet-package.mjs";
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  readServiceSettings,
+  saveServiceSettings,
+  listenerPresent,
+} from "./local-services.mjs";
+const execute = promisify(execFile);
+const userDir = fileURLToPath(new URL("..", import.meta.url));
+const walletCli = walletCliPath();
+async function ctl(...args) {
+  return execute("systemctl", ["--user", ...args], {
+    timeout: 10000,
+    maxBuffer: 16384,
+  });
+}
+export async function guideOwnsProcess({
+  pidFile,
+  expected,
+  expectedEnv = {},
+  inspect = lstat,
+  read = readFile,
+}) {
+  try {
+    const info = await inspect(pidFile);
+    if (
+      !info.isFile() ||
+      info.isSymbolicLink() ||
+      info.uid !== process.getuid() ||
+      info.mode & 0o077 ||
+      info.size > 32
+    )
+      return false;
+    const text = (await read(pidFile, "utf8")).trim();
+    if (!/^[1-9][0-9]*$/.test(text) || Number(text) <= 1) return false;
+    const proc = await inspect(`/proc/${text}`);
+    if (proc.uid !== process.getuid()) return false;
+    const args = (await read(`/proc/${text}/cmdline`, "utf8"))
+      .split("\0")
+      .filter(Boolean);
+    if (JSON.stringify(args) !== JSON.stringify(expected)) return false;
+    if (Object.keys(expectedEnv).length) {
+      const environment = Object.fromEntries(
+        (await read(`/proc/${text}/environ`, "utf8"))
+          .split("\0")
+          .filter(Boolean)
+          .map((line) => {
+            const i = line.indexOf("=");
+            return [line.slice(0, i), line.slice(i + 1)];
+          }),
+      );
+      for (const [key, value] of Object.entries(expectedEnv))
+        if (environment[key] !== value) return false;
+    }
+    // Classification only. Never signal a PID obtained from a stale file.
+    const group = await read(`/proc/${text}/cgroup`, "utf8");
+    if (group.includes("/system.slice/")) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ownership(dataDir, settings) {
+  const paths = {
+    wallet: join(dataDir, "wallet", "wallet.sock"),
+    runtime: {
+      host: "127.0.0.1",
+      port: Number(new URL(settings.runtimeUrl).port),
+    },
+  };
+  for (const role of ["wallet", "runtime"]) {
+    if (!(await listenerPresent(paths[role]))) continue;
+    try {
+      await ctl("is-active", `agentpay-local-${role}.service`);
+      continue;
+    } catch {}
+    const expected =
+      role === "wallet"
+        ? [process.execPath, walletCli, "serve", join(dataDir, "wallet")]
+        : [process.execPath, join(userDir, "src/index.mjs")];
+    if (
+      !(await guideOwnsProcess({
+        pidFile: join(
+          dataDir,
+          "runtime",
+          role === "wallet" ? "wallet-guide.pid" : "user-runtime-guide.pid",
+        ),
+        expected,
+        expectedEnv:
+          role === "runtime"
+            ? {
+                AGENTPAY_USER_STATE_FILE: join(
+                  dataDir,
+                  "runtime",
+                  "invocations.json",
+                ),
+              }
+            : {},
+      }))
+    )
+      return false;
+  }
+  return true;
+}
+export async function finishLocalSetup({
+  dataDir,
+  config,
+  ask,
+  write,
+  platform = process.platform,
+  save = saveServiceSettings,
+  readSettings = readServiceSettings,
+  available = () => ctl("list-jobs", "--no-legend", "--no-pager"),
+  owns = ownership,
+  enable = async () =>
+    execute(
+      process.execPath,
+      [join(userDir, "scripts/autostart.mjs"), "enable"],
+      {
+        env: { ...process.env, AGENTPAY_USER_DATA_DIR: dataDir },
+        timeout: 60000,
+        maxBuffer: 16384,
+      },
+    ),
+}) {
+  if (platform !== "linux") {
+    write(
+      "Automatic startup is not available on this system yet. Your current setup is kept.",
+    );
+    return { state: "unsupported" };
+  }
+  try {
+    await save({
+      dataDir,
+      runtimeUrl: config.runtimeUrl,
+      settlementUrl: config.settlementUrl,
+    });
+    const settings = await readSettings(dataDir);
+    await available();
+    if (!(await owns(dataDir, settings))) {
+      write(
+        "Existing services are managed outside this installer. Automatic startup was not changed.",
+      );
+      return { state: "external" };
+    }
+    if (settings.startupChoice === "disabled") {
+      return { state: "declined" };
+    }
+    if (settings.startupChoice !== "enabled") {
+      write(
+        "\nStart Wallet and Runtime automatically when you log in? Wallet will stay locked until you unlock it.",
+      );
+      let answer;
+      do {
+        answer = String(
+          await ask("Type 'yes' to enable, or 'no' to keep manual startup"),
+        )
+          .trim()
+          .toLowerCase();
+      } while (!["yes", "no", "q"].includes(answer));
+      if (answer !== "yes") {
+        if (answer === "no")
+          await save({
+            dataDir,
+            runtimeUrl: config.runtimeUrl,
+            settlementUrl: config.settlementUrl,
+            startupChoice: "disabled",
+          });
+        write("Current services are kept. Automatic startup was not enabled.");
+        return { state: "declined" };
+      }
+    }
+    await save({
+      dataDir,
+      runtimeUrl: config.runtimeUrl,
+      settlementUrl: config.settlementUrl,
+      startupChoice: "enabled",
+    });
+    await enable();
+    write(
+      "Automatic startup enabled for your next login. Current services are kept; after a restart, use agentpay wallet unlock.",
+    );
+    return { state: "enabled" };
+  } catch {
+    write(
+      "Setup is saved, but automatic startup could not be completed. Retry with agentpay service autostart on. Current processes and Wallet data were kept.",
+    );
+    return { state: "pending" };
+  }
+}

package/src/setup-demo.mjs

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+// UI simulation: callbacks provide only demo initialization and draft collection.
+export async function runSetupDemo({
+  ask,
+  write,
+  check,
+  state,
+  initialize,
+  preview,
+}) {
+  let approved = false,
+    prepared = false,
+    delivered = false,
+    complete = false,
+    draft = null,
+    fields = null,
+    advancing = false;
+  const section = (title, text) =>
+    write(
+      `\n------------------------------------------------------------\n${title}\n------------------------------------------------------------\n${text}`,
+    );
+  const consent = async (text, details) => {
+    while (true) {
+      const answer = (
+        await ask(`${text}\nType 'confirm', 'details', or 'q' to return\n> `)
+      )
+        .trim()
+        .toLowerCase();
+      if (answer === "q") return false;
+      if (answer === "details") {
+        write(JSON.stringify(details, null, 2));
+        continue;
+      }
+      if (answer === "confirm") return true;
+    }
+  };
+  write(
+    "Demo only: no real permission, installation, process or payment. This simulation is not saved after exit.",
+  );
+  while (!complete) {
+    if (!(await check()).ok) return { completed: false, stage: "preflight" };
+    const local = await state();
+    const stage =
+      local.stage !== "initialized"
+        ? "1/4 Create local Wallet"
+        : !approved
+          ? "2/4 Set spending permission"
+          : !prepared
+            ? "3/4 Prepare the official test Skill"
+            : "4/4 Run the paid test";
+    if (!advancing) {
+      section(
+        "> Continue setup",
+        `${stage}\n  * 'continue'  Resume setup\n    'details'   Inspect demo progress\n    'q'         Quit`,
+      );
+      const answer = (await ask("> ")).trim().toLowerCase();
+      if (answer === "q") return { completed: false, mode: "demo" };
+      if (answer === "details") {
+        write(
+          JSON.stringify({ local, approved, prepared, delivered }, null, 2),
+        );
+        continue;
+      }
+      if (answer !== "continue") continue;
+    }
+    advancing = true;
+    try {
+      if (local.stage !== "initialized") {
+        section(stage, "Set a practice unlock secret. No real key is created.");
+        await initialize();
+        continue;
+      }
+      if (!approved) {
+        if (!draft) {
+          const result = await preview(local.delegate, {
+            collectOnly: true,
+            checkpoint: fields,
+            saveInputs: async (value) => {
+              fields = structuredClone(value);
+            },
+          });
+          if (!result?.draft) {
+            advancing = false;
+            continue;
+          }
+          draft = result.draft;
+        }
+        section(
+          stage,
+          `Safe: ${draft.safe}\nBudget: ${draft.budget} ${draft.currency}\nPer-payment limit: ${draft.perPayment} ${draft.currency}\nExpires: ${draft.expiry}\nEligible purchases can spend the whole budget automatically.`,
+        );
+        if (
+          !(await consent(
+            "Confirm to simulate owner authorization and independent Wallet binding.",
+            { calls: draft.calls },
+          ))
+        ) {
+          advancing = false;
+          continue;
+        }
+        approved = true;
+        write("Authorization and Wallet binding complete (demo).");
+        continue;
+      }
+      if (!prepared) {
+        section(
+          stage,
+          "Install and select the official random-number Skill, start Wallet / Runtime and check readiness (simulated). No payment yet.",
+        );
+        prepared = true;
+        write(
+          "Skill selected; Wallet / Runtime running; readiness checks passed (demo).",
+        );
+        continue;
+      }
+      if (!delivered) {
+        section(
+          stage,
+          "Example test cost: 0.001 demo USDC. After verified delivery, Wallet confirms receipt automatically (demo). No real payment.",
+        );
+        if (
+          !(await consent("Confirm to simulate the paid test.", {
+            maximum: "0.001 demo USDC",
+          }))
+        ) {
+          advancing = false;
+          continue;
+        }
+        delivered = true;
+        write("Test delivery verified (demo).");
+      }
+      write(
+        "Official test delivery verified; Wallet confirms receipt automatically (demo). Provider payout may happen earlier.",
+      );
+      complete = true;
+      section(
+        "Setup demo complete",
+        "Connectivity check passed (demo). You can now browse Market and choose Skills you like. This demo has finished; you can close this terminal.",
+      );
+    } catch (error) {
+      advancing = false;
+      write(
+        error.code === "CANCELLED"
+          ? "Paused; completed demo steps are retained until exit."
+          : `Step stopped: ${error.message}`,
+      );
+    }
+  }
+  return { completed: true, mode: "demo", readyToPurchase: false };
+}

package/src/skill-bundle.mjs

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { currentTimeMs } from "./local-time.mjs";
+import { readSkillZip } from "./skill-zip.mjs";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  mkdir,
+  lstat,
+  readFile,
+  writeFile,
+  rename,
+  rm,
+} from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { normalizeServiceReference } from "@c4roa0/agentpay-protocol";
+export const bundleDigest = (bytes) =>
+  createHash("sha256").update(bytes).digest("hex");
+export const skillArchiveLimits = Object.freeze({
+  compressed: 2097152,
+  expanded: 8388608,
+  file: 1048576,
+  entries: 256,
+});
+export function parseSkillBundle(bytes) {
+  const archive = readSkillZip(bytes, skillArchiveLimits),
+    files = Object.fromEntries(archive.files);
+  const entries = Object.keys(files).filter(
+    (name) => name === "SKILL.md" || name.endsWith("/SKILL.md"),
+  );
+  if (entries.length !== 1) throw Error("BUNDLE_INSTRUCTIONS_REQUIRED");
+  const root = entries[0].slice(0, -8);
+  if (
+    archive.entries.some(
+      (e) => root && e.path !== root.slice(0, -1) && !e.path.startsWith(root),
+    )
+  )
+    throw Error("BUNDLE_ROOT_INVALID");
+  if (!files[entries[0]].length || !files[root + "agentpay.json"])
+    throw Error("BUNDLE_MANIFEST_INVALID");
+  const manifest = JSON.parse(files[root + "agentpay.json"].toString("utf8"));
+  if (
+    !manifest ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    typeof manifest.packageName !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$/.test(manifest.packageName) ||
+    typeof manifest.packageVersion !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/.test(manifest.packageVersion)
+  )
+    throw Error("BUNDLE_MANIFEST_INVALID");
+  const services = manifest.services ?? {};
+  if (!services || typeof services !== "object" || Array.isArray(services))
+    throw Error("BUNDLE_SERVICES_INVALID");
+  for (const [alias, reference] of Object.entries(services)) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(alias))
+      throw Error("BUNDLE_SERVICES_INVALID");
+    normalizeServiceReference(reference);
+  }
+  return { manifest, services, root, files, sha256: bundleDigest(bytes) };
+}
+async function privateDir(path) {
+  const st = await lstat(path);
+  if (
+    !st.isDirectory() ||
+    st.isSymbolicLink() ||
+    st.uid !== process.getuid() ||
+    st.mode & 0o077
+  )
+    throw new Error("PRIVATE_USER_DIRECTORY_REQUIRED");
+}
+export async function installSkillBundle({
+  dataDir,
+  bytes,
+  source,
+  publication = null,
+}) {
+  const parsed = parseSkillBundle(bytes);
+  await privateDir(dataDir);
+  const runtime = join(dataDir, "runtime");
+  await privateDir(runtime);
+  const parent = join(runtime, "skill-bundles");
+  await mkdir(parent, { mode: 0o700 }).catch((error) => {
+    if (error.code !== "EEXIST") throw error;
+  });
+  await privateDir(parent);
+  const target = join(
+    parent,
+    `${parsed.manifest.packageName}-${parsed.manifest.packageVersion}-${parsed.sha256}`,
+  );
+  const exists = await lstat(target).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (exists) {
+    await privateDir(target);
+    const original = await readFile(join(target, "publisher.zip"));
+    if (!original.equals(bytes)) throw new Error("BUNDLE_RELEASE_CONFLICT");
+    let locallyModified = false;
+    for (const [name, value] of Object.entries(parsed.files)) {
+      const file = join(target, name);
+      const stat = await lstat(file);
+      if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error("BUNDLE_LOCAL_FILE_INVALID");
+      if (!(await readFile(file)).equals(value)) locallyModified = true;
+    }
+    return { directory: target, changed: false, locallyModified };
+  }
+  // Unique staging directory; only this invocation's incomplete files are removed.
+  const staging = join(parent, `.install-${randomUUID()}`);
+  await mkdir(staging, { mode: 0o700 });
+  try {
+    for (const [name, value] of Object.entries(parsed.files)) {
+      const destination = join(staging, name);
+      await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+      await writeFile(destination, value, { flag: "wx", mode: 0o600 });
+    }
+    await writeFile(join(staging, "publisher.zip"), bytes, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    await writeFile(
+      join(staging, "installation.json"),
+      JSON.stringify(
+        {
+          format: "agentpay.skill-installation.v1",
+          source,
+          sha256: parsed.sha256,
+          publication,
+          installedAtMs: currentTimeMs(),
+        },
+        null,
+        2,
+      ) + "\n",
+      { flag: "wx", mode: 0o600 },
+    );
+    await rename(staging, target);
+    return { directory: target, changed: true, locallyModified: false };
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}

package/src/skill-client.mjs

@@ -0,0 +1,198 @@
+// Generic Skill CLI glue. Business input/output validation is supplied by the Skill;
+// payment authority and request recovery remain in the installed client/Runtime.
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+export const skillClientCapabilities = Object.freeze([
+  "input-snapshots-v1",
+  "output-files-v1",
+  "original-request-v1",
+]);
+import {
+  readServiceOffer,
+  RuntimeClientError,
+  loadRuntimeConnection,
+  userDataDirectory,
+  checkRuntime,
+  selectInvocation,
+  resumeInvocation,
+  invokeService,
+  completeInvocation,
+  cacheResultFile,
+} from "./runtime-client.mjs";
+import { parseServiceReference } from "./service-reference.mjs";
+export async function runSkill({
+  service,
+  args = process.argv.slice(2),
+  env = process.env,
+  validateRequest = (request) => request,
+  inputFiles,
+  prepareRequest,
+  outputFiles,
+  write = (value) => console.log(JSON.stringify(value)),
+  notice = (value) => console.error(value),
+} = {}) {
+  let requestId;
+  try {
+    const reference = parseServiceReference(service),
+      values = [...args],
+      mode = values.shift();
+    const connection = await loadRuntimeConnection({
+      dataDir: userDataDirectory(env),
+      env,
+    });
+    if (mode === "--quote" && values.length === 0) {
+      write({
+        ok: true,
+        result: await readServiceOffer(connection, reference),
+      });
+      return 0;
+    }
+    if (mode === "--check" && values.length === 0) {
+      write(await checkRuntime(connection, reference));
+      return 0;
+    }
+    let checkpoint;
+    if (mode === "--resume" && values.length === 1)
+      checkpoint = await resumeInvocation(connection, reference, values[0]);
+    else if (mode === "--invoke") {
+      const inputText = values.shift();
+      let force = false,
+        units = "1",
+        unitsSeen = false,
+        acceptedTerms,
+        requestId;
+      while (values.length) {
+        const flag = values.shift();
+        if (
+          flag === "--accept-terms" &&
+          acceptedTerms === undefined &&
+          values.length
+        ) {
+          try {
+            acceptedTerms = JSON.parse(values.shift());
+          } catch {
+            throw new RuntimeClientError(
+              "INVALID_ARGUMENTS",
+              "Pass --accept-terms the JSON price/duration read from --quote.",
+            );
+          }
+        } else if (flag === "--force" && !force) force = true;
+        else if (flag === "--units" && !unitsSeen && values.length) {
+          units = values.shift();
+          unitsSeen = true;
+        } else if (
+          flag === "--request-id" &&
+          requestId === undefined &&
+          values.length
+        )
+          requestId = values.shift();
+        else
+          throw new RuntimeClientError(
+            "INVALID_ARGUMENTS",
+            "Use --invoke <JSON> [--units N] [--request-id ID] [--force], --check, --quote or --resume <request-id>.",
+          );
+      }
+      if (force && requestId !== undefined)
+        throw new RuntimeClientError(
+          "INVALID_ARGUMENTS",
+          "Choose --force or --request-id, not both.",
+        );
+      let request;
+      try {
+        request = JSON.parse(inputText);
+      } catch {
+        throw new RuntimeClientError(
+          "INVALID_INPUT",
+          "Provide the business input as JSON.",
+        );
+      }
+      try {
+        request = await validateRequest(request);
+      } catch {
+        throw new RuntimeClientError(
+          "INVALID_INPUT",
+          "Check the business input against this Skill’s instructions.",
+        );
+      }
+      checkpoint = await selectInvocation(
+        connection,
+        reference,
+        {
+          request,
+          requestedMaxUsageUnits: units,
+          ...(acceptedTerms === undefined ? {} : { acceptedTerms }),
+        },
+        { force, ...(requestId === undefined ? {} : { requestId }) },
+      );
+    } else
+      throw new RuntimeClientError(
+        "INVALID_ARGUMENTS",
+        "Use --invoke <JSON> [--units N] [--force], --check, --quote or --resume <request-id>.",
+      );
+    requestId = checkpoint.requestId;
+    notice(
+      `Request: ${requestId}. Matching calls recover or reuse output; --force starts another paid request.`,
+    );
+    const result = await invokeService(connection, reference, checkpoint, {
+      inputFiles,
+      prepareRequest,
+    });
+    await completeInvocation(connection, reference, checkpoint);
+    let files;
+    if (outputFiles) {
+      try {
+        const declarations = await outputFiles(
+          structuredClone(result.result.output),
+        );
+        if (!Array.isArray(declarations) || declarations.length > 20)
+          throw Error("Invalid output file declarations");
+        files = [];
+        for (const file of declarations) {
+          if (
+            !file ||
+            Object.keys(file).some(
+              (k) => !["fileKey", "url", "filename", "sha256"].includes(k),
+            )
+          )
+            throw Error("Invalid output file declaration");
+          files.push(
+            await cacheResultFile(connection, {
+              ...file,
+              orderId: result.result.orderId,
+            }),
+          );
+        }
+      } catch {
+        write({
+          ...result,
+          requestId,
+          fileCache: {
+            state: "incomplete",
+            message:
+              "Delivery is saved. Retry this same request to finish saving files; do not use --force.",
+          },
+        });
+        return 1;
+      }
+    }
+    write({ ...result, requestId, ...(files ? { files } : {}) });
+    return 0;
+  } catch (error) {
+    const known =
+      error instanceof RuntimeClientError ||
+      ["SERVICE_REFERENCE_INVALID"].includes(error.code);
+    write({
+      ok: false,
+      ...(requestId ? { requestId } : {}),
+      error: {
+        code: known ? error.code : "LOCAL_CLIENT_FAILED",
+        message: known
+          ? error.message
+          : "Inspect local AgentPay setup and preserve existing requests.",
+        ...(error.runtimeCode ? { runtimeCode: error.runtimeCode } : {}),
+      },
+    });
+    return 1;
+  }
+}