@atlasauth/pca-llamaindex 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @atlasauth/pca-llamaindex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+LlamaIndex.TS adapter for Proof-Carrying Authority — wrap a `FunctionTool` so every call emits a
+PCActn (and hands you the proof) before the tool runs.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-llamaindex
+# peer dependency, install alongside:
+npm i llamaindex
+```
+
+## Usage
+
+```ts
+import { withPCA } from '@atlasauth/pca-llamaindex';
+
+const guardedRefund = withPCA(
+  agent,
+  { verb: 'stripe.refund', resource: (args) => `charge:${args.charge}`, onProof: (pca) => attach(pca.headers) },
+  refundTool, // your LlamaIndex FunctionTool
+);
+```
+
+The wrapped tool has the same shape, so it drops into your agent's tool list. `agent` comes from
+`@atlasauth/pca`'s facade. This attaches a proof-carrying action; it doesn't authorize — the resource
+server's verifier decides. `llamaindex` is an optional peer dependency and is never imported.
+
+Part of Proof-Carrying Authority — see [`@atlasauth/pca`](../pca).

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LlamaIndex.TS adapter for Proof-Carrying Authority.
+ *
+ * Wrap a LlamaIndex FunctionTool so every call first builds a PCActn (via the core `guard`) — fast-failing
+ * on the agent's local dry-run and handing the proof to your `onProof` so it can forward it to the resource
+ * server — then runs the original tool. Drop-in: the wrapped tool has the SAME shape, so it slots straight
+ * into the `tools` array you hand to a LlamaIndex agent.
+ *
+ * Structurally compatible with the `llamaindex` package (declare `llamaindex` as a peer dependency). We touch
+ * only `call` and preserve `metadata` and every other field, so this works across minor versions without
+ * importing the SDK's runtime.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's verifier
+ * decides. A bypassed wrapper just means the action lacks a valid PCActn and fails server-side.
+ */
+import { type Agent, type PcaCall, bridgeToolCall, pcaHeaders } from '@atlasauth/pca';
+/**
+ * Minimal structural shape of a LlamaIndex FunctionTool. `call` is a METHOD (not an arrow property) on
+ * purpose: method signatures are bivariant, so a tool with concrete argument types assigns cleanly to the
+ * general `LlamaIndexTool` when collected in a `tools` array — no `any`, no casts.
+ */
+export interface LlamaIndexTool<ARGS = Record<string, unknown>, RESULT = unknown> {
+    metadata: {
+        name: string;
+        description?: string;
+        parameters?: unknown;
+    };
+    call(input: ARGS): Promise<RESULT> | RESULT;
+    [k: string]: unknown;
+}
+export interface GuardToolSpec<ARGS> {
+    /** Catalog verb this tool maps to (e.g. `stripe.refund`). */
+    verb: string;
+    /** Resource for the call: fixed, or derived from the tool args. */
+    resource: string | ((args: ARGS) => string);
+    /** Audience (resource-server / instance id); falls back to the agent's default. */
+    aud?: string;
+    /** Fast-fail on the local dry-run before executing (default true). */
+    failFast?: boolean;
+    /** Receive the PCActn so `call` can forward it (e.g. as request headers) to the resource server. */
+    onProof?: (pca: PcaCall, args: ARGS) => void;
+}
+/** Wrap a LlamaIndex FunctionTool so each call emits + attaches a PCActn before the original `call` runs. */
+export declare function withPCA<ARGS extends Record<string, unknown>, RESULT>(agent: Agent, spec: GuardToolSpec<ARGS>, tool: LlamaIndexTool<ARGS, RESULT>): LlamaIndexTool<ARGS, RESULT>;
+export { bridgeToolCall, pcaHeaders, type PcaCall };

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * LlamaIndex.TS adapter for Proof-Carrying Authority.
+ *
+ * Wrap a LlamaIndex FunctionTool so every call first builds a PCActn (via the core `guard`) — fast-failing
+ * on the agent's local dry-run and handing the proof to your `onProof` so it can forward it to the resource
+ * server — then runs the original tool. Drop-in: the wrapped tool has the SAME shape, so it slots straight
+ * into the `tools` array you hand to a LlamaIndex agent.
+ *
+ * Structurally compatible with the `llamaindex` package (declare `llamaindex` as a peer dependency). We touch
+ * only `call` and preserve `metadata` and every other field, so this works across minor versions without
+ * importing the SDK's runtime.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's verifier
+ * decides. A bypassed wrapper just means the action lacks a valid PCActn and fails server-side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pcaHeaders = exports.bridgeToolCall = void 0;
+exports.withPCA = withPCA;
+const pca_1 = require("@atlasauth/pca");
+Object.defineProperty(exports, "bridgeToolCall", { enumerable: true, get: function () { return pca_1.bridgeToolCall; } });
+Object.defineProperty(exports, "pcaHeaders", { enumerable: true, get: function () { return pca_1.pcaHeaders; } });
+/** Wrap a LlamaIndex FunctionTool so each call emits + attaches a PCActn before the original `call` runs. */
+function withPCA(agent, spec, tool) {
+    const run = (0, pca_1.guard)(agent, {
+        verb: spec.verb,
+        resource: spec.resource,
+        ...(spec.aud !== undefined ? { aud: spec.aud } : {}),
+        ...(spec.failFast !== undefined ? { failFast: spec.failFast } : {}),
+    }, async (args, pca) => {
+        spec.onProof?.(pca, args);
+        return (await tool.call(args));
+    });
+    return { ...tool, call: (input) => run(input) };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AA6BH,0BAmBC;AA9CD,wCAA6F;AAgDpF,+FAhD0B,oBAAc,OAgD1B;AAAE,2FAhDiC,gBAAU,OAgDjC;AAtBnC,6GAA6G;AAC7G,SAAgB,OAAO,CACrB,KAAY,EACZ,IAAyB,EACzB,IAAkC;IAElC,MAAM,GAAG,GAAG,IAAA,WAAK,EACf,KAAK,EACL;QACE,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,EACD,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAW,CAAC;IAC3C,CAAC,CACF,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,KAAW,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@atlasauth/pca-llamaindex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "LlamaIndex.TS adapter for Proof-Carrying Authority: wrap a FunctionTool so each call emits a PCActn before it runs.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.1.0"
+  },
+  "peerDependencies": {
+    "llamaindex": "^0.8 || ^0.9 || ^0.10"
+  },
+  "peerDependenciesMeta": {
+    "llamaindex": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }