pi-cloudflare 0.5.4 → 0.6.0

package/dist/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,WAAW,GAAG,SAAS,KAC5B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CACxD;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAcD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,EAAE,EACrB,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAChF,gBAAgB,EAAE,CAiBpB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;CACvC,CAAC,GACD,gBAAgB,EAAE,CAIpB"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAGxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,cAAc,CAAC,CAAA;CAC7B;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAeD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,EAAE,EACrB,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAChF,gBAAgB,EAAE,CAkBpB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;CACvC,CAAC,GACD,gBAAgB,EAAE,CAIpB"}

package/dist/proxy.js

@@ -11,8 +11,8 @@ function toToolContent(result) {
         : { content: output };
 }
 /**
- * Build pi tool registrations for one upstream server. Pure function over
- * injected dependencies so it unit tests without network or a pi session.
+ * Build host-neutral tool registrations for one upstream server. The raw
+ * schema is retained for MCP while Pi receives the TypeBox representation.
  */
 export function buildToolRegistrations(prefix, tools, callUpstream) {
     return tools.map((tool) => {
@@ -24,6 +24,7 @@ export function buildToolRegistrations(prefix, tools, callUpstream) {
             name,
             label: name,
             description,
+            inputSchema: tool.inputSchema,
             parameters: Type.Unsafe(tool.inputSchema),
             execute: async (_toolCallId, params) => {
                 const result = await callUpstream(tool.name, params ?? {});

package/dist/proxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAsB9B,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9D,CAAC;IACD,MAAM,MAAM,GAAG,MAAkD,CAAA;IACjE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IAC1E,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO;QAC1D,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;QACpC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,KAAqB,EACrB,YAAiF;IAEjF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;YAC1C,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE;YACrD,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAA;QAChD,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,IAAI;YACX,WAAW;YACX,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;YACzC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC,CAAA;gBAC1D,OAAO,aAAa,CAAC,MAAM,CAAC,CAAA;YAC9B,CAAC;SACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,WAIE;IAEF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CACxC,sBAAsB,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CACjF,CAAA;AACH,CAAC"}
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAyB9B,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9D,CAAC;IACD,MAAM,MAAM,GAAG,MAAkD,CAAA;IACjE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,OAAqC,CAAC,CAAC,CAAC,EAAE,CAAA;IAClG,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAA+B,CAAA;IAC5F,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO;QAC1D,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;QACpC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,KAAqB,EACrB,YAAiF;IAEjF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;YAC1C,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE;YACrD,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAA;QAChD,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,IAAI;YACX,WAAW;YACX,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;YACzC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC,CAAA;gBAC1D,OAAO,aAAa,CAAC,MAAM,CAAC,CAAA;YAC9B,CAAC;SACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,WAIE;IAEF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CACxC,sBAAsB,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CACjF,CAAA;AACH,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,52 @@
+import { type PiCloudflareConfig } from './config.js';
+import { type ToolRegistration } from './proxy.js';
+import { type CloudflareServerId } from './servers.js';
+import { type StoredServerTokens } from './token-store.js';
+export interface CloudflareRuntimeOptions {
+    /** Shared runtime configuration. Native Pi supplies settings; portable hosts normally use defaults. */
+    config?: PiCloudflareConfig;
+    /** OAuth token file. Defaults to Pi's legacy ~/.pi/cloudflare-tokens.json for compatibility. */
+    tokenFile?: string;
+    /** Optional local setup script used in portable re-authentication hints. */
+    setupScript?: string;
+    /** Warning sink. Native Pi uses console.warn; the stdio server uses stderr. */
+    warn?: (message: string) => void;
+}
+/** Exact command that re-authorizes one server; shown to agents, never guessed. */
+export declare function reauthHint(serverId: string, options?: {
+    tokenFile?: string;
+    setupScript?: string;
+}): string;
+/** True when a failure smells like rejected credentials rather than a broken server. */
+export declare function isAuthFailure(error: unknown): boolean;
+/**
+ * Adopt rotations performed by sibling native Pi sessions. Kept as a public
+ * compatibility helper; portable runtimes use their explicit plugin-data path.
+ */
+export declare function syncFromFile(entry: {
+    definition: {
+        id: CloudflareServerId;
+    };
+    stored?: StoredServerTokens;
+}, home?: string): void;
+export declare class CloudflareRuntime {
+    private entries;
+    private readonly config;
+    private readonly tokenFile;
+    private readonly setupScript;
+    private readonly warn;
+    constructor(options?: CloudflareRuntimeOptions);
+    private hint;
+    private reconnect;
+    /** Refresh unconditionally after a credential rejection, persist, and reconnect. */
+    private refreshNow;
+    /** Refresh an OAuth token that is expired (or nearly so). Static tokens skip refresh. */
+    private ensureFreshToken;
+    /**
+     * Connect enabled Cloudflare servers independently and expose one curated
+     * cf_* tool surface. One unavailable server never prevents the others.
+     */
+    start(): Promise<ToolRegistration[]>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEpE,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACzE,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAA;AACrB,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAA;AAazB,MAAM,WAAW,wBAAwB;IACvC,uGAAuG;IACvG,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAMD,mFAAmF;AACnF,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,MAAM,CAYR;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAYD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE;IAAE,UAAU,EAAE;QAAE,EAAE,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAE,EAC9E,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAEN;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;gBAEpC,OAAO,GAAE,wBAA6B;IAOlD,OAAO,CAAC,IAAI;YAOE,SAAS;IAUvB,oFAAoF;YACtE,UAAU;IAgBxB,yFAAyF;YAC3E,gBAAgB;IAe9B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAiFpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAI5B"}

package/dist/runtime.js

@@ -0,0 +1,186 @@
+import { Type } from 'typebox';
+import { connectServer } from './client.js';
+import { resolveConfig } from './config.js';
+import { refreshAccessToken } from './oauth.js';
+import { buildAllRegistrations } from './proxy.js';
+import { CLOUDFLARE_SERVERS, } from './servers.js';
+import { isExpired, readTokenFileAt, tokenFilePath, writeTokenFileAt, } from './token-store.js';
+function quoteArg(value) {
+    return JSON.stringify(value);
+}
+/** Exact command that re-authorizes one server; shown to agents, never guessed. */
+export function reauthHint(serverId, options = {}) {
+    const setupCommand = options.tokenFile && options.setupScript
+        ? `node ${quoteArg(options.setupScript)} --token-file ${quoteArg(options.tokenFile)} --only ${serverId}`
+        : `npx -p pi-cloudflare pi-cloudflare-setup --only ${serverId}`;
+    return (`${serverId} needs re-authentication (token expired, revoked, or never granted). ` +
+        `For temporary access, run in a terminal (approve in the browser when it opens): ` +
+        `${setupCommand}. ` +
+        `For persistent access across sessions, create an API token instead — ` +
+        `see the cloudflare-auth-setup skill (it asks once, then sets up either path).`);
+}
+/** True when a failure smells like rejected credentials rather than a broken server. */
+export function isAuthFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\b401\b|\b403\b|unauthorized|invalid_token|invalid_grant|token refresh failed|expired|forbidden|authenticate/i.test(message);
+}
+function syncFromTokenFile(entry, path) {
+    const latest = readTokenFileAt(path)?.servers[entry.definition.id];
+    if (latest && latest.refreshToken !== entry.stored?.refreshToken) {
+        entry.stored = latest;
+    }
+}
+/**
+ * Adopt rotations performed by sibling native Pi sessions. Kept as a public
+ * compatibility helper; portable runtimes use their explicit plugin-data path.
+ */
+export function syncFromFile(entry, home) {
+    syncFromTokenFile(entry, tokenFilePath(home));
+}
+export class CloudflareRuntime {
+    entries = [];
+    config;
+    tokenFile;
+    setupScript;
+    warn;
+    constructor(options = {}) {
+        this.config = options.config ?? {};
+        this.tokenFile = options.tokenFile ?? tokenFilePath();
+        this.setupScript = options.setupScript;
+        this.warn = options.warn ?? (() => undefined);
+    }
+    hint(serverId) {
+        return reauthHint(serverId, {
+            tokenFile: this.setupScript ? this.tokenFile : undefined,
+            setupScript: this.setupScript,
+        });
+    }
+    async reconnect(entry) {
+        await entry.connection?.close().catch(() => undefined);
+        const token = entry.staticToken ?? entry.stored?.accessToken;
+        entry.connection = await connectServer(entry.definition, {
+            apiToken: token,
+            timeoutMs: entry.timeoutMs,
+        });
+        entry.connectedToken = token;
+    }
+    /** Refresh unconditionally after a credential rejection, persist, and reconnect. */
+    async refreshNow(entry) {
+        syncFromTokenFile(entry, this.tokenFile);
+        const stored = entry.stored;
+        if (!stored?.refreshToken)
+            throw new Error(`${entry.definition.id}: no refresh token stored`);
+        const fresh = await refreshAccessToken({
+            tokenEndpoint: stored.tokenEndpoint,
+            clientId: stored.clientId,
+            refreshToken: stored.refreshToken,
+        });
+        entry.stored = { ...stored, ...fresh };
+        const file = readTokenFileAt(this.tokenFile) ?? { version: 1, servers: {} };
+        file.servers[entry.definition.id] = entry.stored;
+        writeTokenFileAt(file.servers, this.tokenFile);
+        await this.reconnect(entry);
+    }
+    /** Refresh an OAuth token that is expired (or nearly so). Static tokens skip refresh. */
+    async ensureFreshToken(entry) {
+        if (entry.staticToken)
+            return entry.staticToken;
+        syncFromTokenFile(entry, this.tokenFile);
+        const stored = entry.stored;
+        if (!stored)
+            return undefined;
+        if (!isExpired(stored) || !stored.refreshToken) {
+            if (!entry.connection || entry.connectedToken !== stored.accessToken) {
+                await this.reconnect(entry);
+            }
+            return stored.accessToken;
+        }
+        await this.refreshNow(entry);
+        return entry.stored?.accessToken;
+    }
+    /**
+     * Connect enabled Cloudflare servers independently and expose one curated
+     * cf_* tool surface. One unavailable server never prevents the others.
+     */
+    async start() {
+        await this.stop();
+        const registrations = [];
+        const config = resolveConfig(this.config);
+        const file = readTokenFileAt(this.tokenFile);
+        const definitions = CLOUDFLARE_SERVERS.filter((server) => config.enabledServerIds.includes(server.id));
+        for (const definition of definitions) {
+            const entry = {
+                definition,
+                timeoutMs: config.connectTimeoutMs,
+                staticToken: definition.id === 'api' ? this.config.apiToken : undefined,
+            };
+            try {
+                entry.stored = file?.servers[definition.id];
+                await this.ensureFreshToken(entry);
+                if (!entry.connection)
+                    await this.reconnect(entry);
+                const tools = (await entry.connection?.listTools()) ?? [];
+                const serverRegistrations = buildAllRegistrations([
+                    {
+                        prefix: definition.prefix,
+                        tools,
+                        callTool: async (name, params) => {
+                            if (!entry.connection)
+                                throw new Error(`${definition.id}: not connected`);
+                            return entry.connection.callTool(name, params);
+                        },
+                    },
+                ]);
+                for (const registration of serverRegistrations) {
+                    registrations.push({
+                        ...registration,
+                        execute: async (toolCallId, params, signal) => {
+                            try {
+                                await this.ensureFreshToken(entry);
+                                return await registration.execute(toolCallId, params, signal);
+                            }
+                            catch (error) {
+                                if (!isAuthFailure(error) || entry.staticToken || !entry.stored?.refreshToken) {
+                                    throw error;
+                                }
+                                try {
+                                    await this.refreshNow(entry);
+                                    return await registration.execute(toolCallId, params, signal);
+                                }
+                                catch {
+                                    const detail = error instanceof Error ? error.message : String(error);
+                                    throw new Error(`${definition.id}: request rejected (${detail}). ${this.hint(definition.id)}`);
+                                }
+                            }
+                        },
+                    });
+                }
+                this.entries.push(entry);
+            }
+            catch (error) {
+                this.warn(`${definition.id}: unavailable (${error instanceof Error ? error.message : String(error)}).`);
+                if (isAuthFailure(error)) {
+                    const hint = this.hint(definition.id);
+                    registrations.push({
+                        name: `${definition.prefix}reauthenticate`,
+                        label: `${definition.prefix}reauthenticate`,
+                        description: `${definition.id} is not authenticated. Call this tool for exact re-authentication instructions.`,
+                        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+                        parameters: Type.Object({}),
+                        execute: async () => ({
+                            content: [{ type: 'text', text: hint }],
+                        }),
+                    });
+                    this.warn(hint);
+                }
+                await entry.connection?.close().catch(() => undefined);
+            }
+        }
+        return registrations;
+    }
+    async stop() {
+        await Promise.all(this.entries.map((entry) => entry.connection?.close().catch(() => undefined)));
+        this.entries = [];
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/token-store.d.ts

@@ -1,20 +1,26 @@
-import type { CloudflareServerId } from './servers.js';
 import type { OAuthTokens } from './oauth.js';
+import type { CloudflareServerId } from './servers.js';
 export interface StoredServerTokens extends OAuthTokens {
     clientId: string;
     tokenEndpoint: string;
 }
-interface TokenFile {
+export interface TokenFile {
     version: 1;
     servers: Partial<Record<CloudflareServerId, StoredServerTokens>>;
 }
 export declare function tokenFilePath(home?: string): string;
-/** Read stored per-server OAuth tokens. Missing file means not authenticated. */
+/** Read stored per-server OAuth tokens from an explicit file path. */
+export declare function readTokenFileAt(path: string): TokenFile | undefined;
+/** Read the legacy native-Pi token store. Missing file means not authenticated. */
 export declare function readTokenFile(home?: string): TokenFile | undefined;
 /**
- * Persist per-server tokens with owner-only permissions. Never logs values.
- * Writes atomically (temp file plus rename) so concurrent Pi sessions
- * cannot interleave partial writes into a corrupt token file.
+ * Persist per-server tokens at an explicit path with owner-only permissions.
+ * Writes atomically so concurrent agent sessions cannot leave a partial file.
+ */
+export declare function writeTokenFileAt(servers: Partial<Record<CloudflareServerId, StoredServerTokens>>, path: string): void;
+/**
+ * Persist per-server tokens with owner-only permissions in native Pi's
+ * ~/.pi/cloudflare-tokens.json.
  */
 export declare function writeTokenFile(servers: Partial<Record<CloudflareServerId, StoredServerTokens>>, home?: string): void;
 export declare function isExpired(tokens: Pick<OAuthTokens, 'expiresAt'>, skewMs?: number): boolean;
@@ -23,5 +29,4 @@ export declare function partitionServers(ids: CloudflareServerId[], stored: Part
     fresh: CloudflareServerId[];
     needed: CloudflareServerId[];
 };
-export {};
 //# sourceMappingURL=token-store.d.ts.map

package/dist/token-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../src/token-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,UAAU,SAAS;IACjB,OAAO,EAAE,CAAC,CAAA;IACV,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,CAAA;CACjE;AAED,wBAAgB,aAAa,CAAC,IAAI,SAAY,GAAG,MAAM,CAEtD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,SAAY,GAAG,SAAS,GAAG,SAAS,CAUrE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,EAChE,IAAI,SAAY,GACf,IAAI,CASN;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,MAAM,SAAS,GAAG,OAAO,CAE1F;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,kBAAkB,EAAE,EACzB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,GAAG,SAAS,GAC1E;IAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAAC,MAAM,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAS/D"}
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../src/token-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,CAAC,CAAA;IACV,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,CAAA;CACjE;AAED,wBAAgB,aAAa,CAAC,IAAI,SAAY,GAAG,MAAM,CAEtD;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CASnE;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,SAAY,GAAG,SAAS,GAAG,SAAS,CAErE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,EAChE,IAAI,EAAE,MAAM,GACX,IAAI,CAQN;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,EAChE,IAAI,SAAY,GACf,IAAI,CAEN;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,MAAM,SAAS,GAAG,OAAO,CAE1F;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,kBAAkB,EAAE,EACzB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,GAAG,SAAS,GAC1E;IAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAAC,MAAM,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAS/D"}

package/dist/token-store.js

@@ -1,12 +1,11 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 export function tokenFilePath(home = homedir()) {
     return join(home, '.pi', 'cloudflare-tokens.json');
 }
-/** Read stored per-server OAuth tokens. Missing file means not authenticated. */
-export function readTokenFile(home = homedir()) {
-    const path = tokenFilePath(home);
+/** Read stored per-server OAuth tokens from an explicit file path. */
+export function readTokenFileAt(path) {
     if (!existsSync(path))
         return undefined;
     try {
@@ -19,14 +18,16 @@ export function readTokenFile(home = homedir()) {
         return undefined;
     }
 }
+/** Read the legacy native-Pi token store. Missing file means not authenticated. */
+export function readTokenFile(home = homedir()) {
+    return readTokenFileAt(tokenFilePath(home));
+}
 /**
- * Persist per-server tokens with owner-only permissions. Never logs values.
- * Writes atomically (temp file plus rename) so concurrent Pi sessions
- * cannot interleave partial writes into a corrupt token file.
+ * Persist per-server tokens at an explicit path with owner-only permissions.
+ * Writes atomically so concurrent agent sessions cannot leave a partial file.
  */
-export function writeTokenFile(servers, home = homedir()) {
-    const path = tokenFilePath(home);
-    mkdirSync(join(home, '.pi'), { recursive: true });
+export function writeTokenFileAt(servers, path) {
+    mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify({ version: 1, servers }, null, 2) + '\n', {
         mode: 0o600,
@@ -34,6 +35,13 @@ export function writeTokenFile(servers, home = homedir()) {
     chmodSync(tmp, 0o600);
     renameSync(tmp, path);
 }
+/**
+ * Persist per-server tokens with owner-only permissions in native Pi's
+ * ~/.pi/cloudflare-tokens.json.
+ */
+export function writeTokenFile(servers, home = homedir()) {
+    writeTokenFileAt(servers, tokenFilePath(home));
+}
 export function isExpired(tokens, skewMs = 30_000) {
     return Date.now() + skewMs >= tokens.expiresAt;
 }

package/dist/token-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../src/token-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACnG,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAehC,MAAM,UAAU,aAAa,CAAC,IAAI,GAAG,OAAO,EAAE;IAC5C,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,wBAAwB,CAAC,CAAA;AACpD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,IAAI,GAAG,OAAO,EAAE;IAC5C,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAA;QAClE,IAAI,MAAM,EAAE,OAAO,KAAK,CAAC,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAA;QACjF,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgE,EAChE,IAAI,GAAG,OAAO,EAAE;IAEhB,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;IAChC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACjD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAA;IACxC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;QAC1E,IAAI,EAAE,KAAK;KACZ,CAAC,CAAA;IACF,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACrB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAsC,EAAE,MAAM,GAAG,MAAM;IAC/E,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,IAAI,MAAM,CAAC,SAAS,CAAA;AAChD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAC9B,GAAyB,EACzB,MAA2E;IAE3E,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,MAAM,GAAyB,EAAE,CAAA;IACvC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;;YACzC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACtB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC1B,CAAC"}
+{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../src/token-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACnG,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAezC,MAAM,UAAU,aAAa,CAAC,IAAI,GAAG,OAAO,EAAE;IAC5C,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,wBAAwB,CAAC,CAAA;AACpD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAA;QAClE,IAAI,MAAM,EAAE,OAAO,KAAK,CAAC,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAA;QACjF,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,IAAI,GAAG,OAAO,EAAE;IAC5C,OAAO,eAAe,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAA;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgE,EAChE,IAAY;IAEZ,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC7C,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAA;IACxC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;QAC1E,IAAI,EAAE,KAAK;KACZ,CAAC,CAAA;IACF,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACrB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgE,EAChE,IAAI,GAAG,OAAO,EAAE;IAEhB,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAsC,EAAE,MAAM,GAAG,MAAM;IAC/E,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,IAAI,MAAM,CAAC,SAAS,CAAA;AAChD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAC9B,GAAyB,EACzB,MAA2E;IAE3E,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,MAAM,GAAyB,EAAE,CAAA;IACvC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;;YACzC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACtB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC1B,CAAC"}

package/mcp.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "cloudflare": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/dist/mcp-server.js"],
+      "env": {
+        "PI_CLOUDFLARE_PLUGIN_ROOT": "${PLUGIN_ROOT}",
+        "PI_CLOUDFLARE_TOKEN_FILE": "${PLUGIN_DATA}/cloudflare-tokens.json"
+      },
+      "cwd": "${PLUGIN_ROOT}"
+    }
+  }
+}

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "pi-cloudflare",
-  "version": "0.5.4",
-  "description": "Pi extension proxying Cloudflare's official MCP servers (API, docs, bindings, builds, observability) with cf_ prefixed tools.",
+  "version": "0.6.0",
+  "description": "Cloudflare Agent Plugin and native Pi extension providing official skills and cf_-prefixed MCP tools.",
   "keywords": [
+    "agent-plugin",
+    "agent-skills",
     "cloudflare",
     "extension",
     "mcp",
@@ -23,6 +25,8 @@
   "files": [
     "dist",
     "skills",
+    "plugin.json",
+    "mcp.json",
     "README.md"
   ],
   "type": "module",
@@ -47,7 +51,7 @@
     "perf:check": "node scripts/performance-audit.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build",
-    "test": "node --test test/config.test.mjs test/servers.test.mjs test/proxy.test.mjs test/oauth.test.mjs test/token-store.test.mjs test/auth-recovery.test.mjs && npm run perf:check",
+    "test": "node --test test/config.test.mjs test/servers.test.mjs test/proxy.test.mjs test/oauth.test.mjs test/token-store.test.mjs test/auth-recovery.test.mjs test/plugin.test.mjs",
     "pretest": "npm run build"
   },
   "dependencies": {

package/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "pi-cloudflare",
+  "version": "0.6.0",
+  "description": "Cloudflare skills and cf_-prefixed MCP tools, with a native Pi adapter and an Agent Plugins 1.0 portable runtime.",
+  "author": {
+    "name": "0xPlayerOne",
+    "url": "https://github.com/0xPlayerOne"
+  },
+  "homepage": "https://github.com/0xPlayerOne/pi-cloudflare#readme",
+  "repository": "https://github.com/0xPlayerOne/pi-cloudflare",
+  "license": "MIT",
+  "keywords": [
+    "cloudflare",
+    "agent-plugin",
+    "mcp",
+    "agent-skills",
+    "pi"
+  ]
+}

package/skills/cloudflare-auth-setup/SKILL.md

@@ -5,14 +5,14 @@ description: Set up Cloudflare authentication from any state. Use before any Clo
 
 # Cloudflare Auth Setup (Router)
 
-This skill runs **before** any Cloudflare work when authentication is not already proven. Never guess at credentials and never loop a rejected auth wall — triage, ask once, then set up exactly one path.
+This skill runs **before** Cloudflare work when authentication is not already proven. Never guess at credentials and never loop a rejected auth wall — triage, ask once, then set up exactly one path. The package can run as native Pi or as an Agent Plugin, so never assume a `~/.pi` path unless the host is actually Pi.
 
 ## Step 0 — What state are we in?
 
 Check in order, stop at the first hit:
 
-1. **API token configured?** `pi-cloudflare.apiToken` setting (or `CLOUDFLARE_API_TOKEN` env) present → verify with one cheap read (`GET /user`). Works → done, proceed with the task.
-2. **Browser OAuth fresh?** Stored tokens exist and unexpired (or a silent refresh succeeds) → done.
+1. **API access already works?** Verify with one cheap `cf_api_*` read. A native Pi host may source this from `pi-cloudflare.apiToken`; an Agent Plugin host may inject `CLOUDFLARE_API_TOKEN` through its own secret/environment mechanism. Do not inspect or print the secret.
+2. **Browser OAuth already works?** Run one cheap tool in the required `cf_<server>_*` namespace. Silent refresh is automatic when stored credentials are usable.
 3. **Otherwise → unauthenticated.** Go to Step 1. This includes expired/revoked tokens and any 401/403/`invalid_grant` from a tool call.
 
 ## Step 1 — Stop and ask (one question, three options)
@@ -20,34 +20,40 @@ Check in order, stop at the first hit:
 Do not pick for the user. Ask:
 
 > Cloudflare isn't authenticated. How should I set it up?
-> 1. **API token (recommended for repeat work)** — I create it in your dashboard, store it, verify it. Survives restarts, no browser popups afterward.
-> 2. **Browser OAuth (quickest for one-off work)** — you approve once in a browser window; lasts about an hour.
-> 3. **I'll paste a token** — you create it in the dashboard yourself and hand me the value; I store and verify it.
+> 1. **API token (recommended for repeat automation)** — create a scoped token, store it through this host's secret mechanism, then verify it.
+> 2. **Browser OAuth (quickest)** — run the exact re-authentication command returned by the Cloudflare tool and approve once in a browser.
+> 3. **I already have a token** — enter it locally through the host's secret/environment mechanism, never in chat, then verify it.
 
-If the user already answered implicitly ("just set it up", "use a token"), skip the question and proceed — note the assumption.
+If the user already answered implicitly (for example, "use OAuth" or "use a token"), skip the question and proceed while noting the assumption.
 
 ## Step 2 — Check what this environment can do
 
 | Capability | How to tell | If missing |
 |---|---|---|
-| Drive a browser (`browser_*` tools or equivalent) | Tool list contains browser automation | Token creation becomes **guided manual**: give exact dashboard clicks (see cloudflare-api-token skill UI path), user pastes the secret back, you store + verify. OAuth becomes **manual**: user runs the setup command in their own terminal. |
-| Open a terminal for the setup CLI | You can execute shell | Otherwise do everything in-chat: manual dashboard steps + paste-back. |
-| Existing dashboard session | Previous browser profile with a login | Without it, every browser path starts with a human sign-in (SSO/2FA/passkeys are theirs to complete). |
+| Drive a browser (`browser_*` tools or equivalent) | Tool list contains browser automation | Token creation becomes guided manual: give exact dashboard clicks from `cloudflare-api-token`. OAuth still works by having the user run the returned setup command in their own terminal. |
+| Open a terminal | Shell execution is available | Otherwise provide the exact local command and let the human run it. Never ask for an OAuth token or API token in chat. |
+| Existing dashboard session | Browser profile is already signed in | Without it, the human completes sign-in/SSO/2FA/passkeys before continuing. |
 
-The matrix composes: no browser + no terminal still works (pure manual + paste-back). Never declare the task impossible — degrade to the manual path with precise steps.
+Do not declare authentication impossible merely because browser automation is unavailable; degrade to the manual local flow with precise steps.
 
 ## Step 3 — Execute exactly one path
 
-- **API token** → `cloudflare-api-token` skill (create), including its store step (env file + shell block + settings reference + verify). On a lost secret later: `cloudflare-token-roll`. On scope changes: `cloudflare-token-scopes`.
-- **Browser OAuth** → run the per-server setup command from the error hint (`pi-cloudflare-setup --only <server>`); the human approves in the opened window. Re-verify with one cheap read. Warn that it expires in about an hour.
-- **Pasted token** → store exactly like a created one (same store step, same file perms), verify, destroy chat-visible copies from your side (never write the value to repo files, logs, or docs).
+- **API token** → load `cloudflare-api-token` for scopes and creation. Store the resulting secret according to the active host:
+  - **Native Pi:** reference `CLOUDFLARE_API_TOKEN` from `pi-cloudflare.apiToken`; never put the literal in settings.
+  - **Agent Plugin:** Agent Plugins 1.0 has no portable secret-reference field. Use the client's secret/environment configuration so the MCP subprocess receives `CLOUDFLARE_API_TOKEN`.
+- **Browser OAuth** → call `cf_<server>_reauthenticate` and run the **exact command returned by that tool**. Native Pi points at its Pi token store; Agent Plugin hosts point at their client-managed `${PLUGIN_DATA}` token file. Do not compose or substitute a token path yourself. The human approves in the browser, then re-verify with a cheap read.
+- **Existing API token** → enter it locally using the same host-specific secret mechanism above. Never paste it into chat or write it to repository files, logs, issues, or docs.
+
+On a lost API-token secret later, load `cloudflare-token-roll`. On scope changes, load `cloudflare-token-scopes`.
 
 ## Step 4 — Prove it before the real task
 
-One cheap read in the task's domain (identity, one list call). Only then continue. If it fails, you misdiagnosed Step 0 — restart triage instead of retry-looping.
+Run one cheap read in the task's domain (identity or one list call). Only then continue. If it fails, restart triage instead of retry-looping.
 
 ## Rules
 
-- One auth question per session unless the state changes; remember the answer.
-- Secrets: `chmod 600` while they live, settings hold references (`${...}`) never literals, temp copies destroyed, values never land in repos, issues, or docs.
-- A 403 naming a missing group after setup is a scoping task (`cloudflare-token-scopes`), not an auth failure — do not restart triage.
+- One auth question per session unless the state changes.
+- Secrets never belong in chat, repository files, issues, logs, or documentation.
+- Native Pi settings hold environment references (`${...}`), never secret literals.
+- Agent Plugin hosts use client-managed secret/environment configuration for static API tokens and `${PLUGIN_DATA}` only for the package-managed OAuth token store.
+- A 403 naming a missing permission group after setup is a scoping task (`cloudflare-token-scopes`), not a reason to retry auth indefinitely.

package/skills/cloudflare-token-roll/SKILL.md

@@ -16,19 +16,18 @@ There is no public roll endpoint (`POST /user/tokens/:id/roll` returns `7000 No
 
 1. My Profile → API Tokens → token row Actions → Roll.
 2. Menu interaction notes: open the Actions menu, then drive the dialog with DOM clicks if a11y clicks stall (dialog buttons sometimes need `querySelector` + `.click()` while a11y clicks dismiss). Confirm only the intended token (dialog names it — read it back before confirming).
-3. The secret modal (`Token rolled successfully` / `Copy your API token now`) holds the **only copy**. Capture `cfut_...` immediately.
+3. The secret modal (`Token rolled successfully` / `Copy your API token now`) holds the **only copy**. Capture `cfut_...` immediately without printing it in chat or logs.
 4. Click Done. Verify the token row still shows Active.
 5. Validate before handoff: `GET /user` (identity), one scoped read per newly relied-upon group (see cloudflare-api-token skill matrix). `GET /user/tokens/:id` confirming policies is safe (never returns the secret).
-6. **Store it for them — never hand off manual steps.** The user must not need to touch anything:
-   - Write `export CLOUDFLARE_API_TOKEN="<secret>"` to `~/.pi/cloudflare-api-token` (mode `0600`, no other content that matters).
-   - Ensure `~/.zshrc` sources it inside a marked idempotent block (`# >>> pi-managed: cloudflare-api-token >>>` … `# <<< pi-managed: cloudflare-api-token <<<`), replacing any previous block.
-   - Set `~/.pi/agent/settings.json` → `pi-cloudflare.apiToken` to the literal string `${CLOUDFLARE_API_TOKEN}` (reference, never the secret). Preserve every other key byte-for-byte in meaning.
-   - Verify: fresh interactive shell resolves a 53-char value; settings parses; one live API read succeeds.
-   - Tell the user to open a new terminal (or `source ~/.zshrc`) and restart Pi sessions so the new environment is picked up.
-7. Destroy temp copies. Report stored + verified **without printing the secret**.
+6. **Store it through the active host's secret mechanism — never put the literal in repository configuration.**
+   - **Native Pi:** write `export CLOUDFLARE_API_TOKEN="<secret>"` to `~/.pi/cloudflare-api-token` (mode `0600`); ensure `~/.zshrc` sources it inside the marked idempotent block; set `~/.pi/agent/settings.json` → `pi-cloudflare.apiToken` to the literal reference `${CLOUDFLARE_API_TOKEN}`; preserve every other setting; then verify a fresh shell and one live API read.
+   - **Agent Plugin:** Agent Plugins 1.0 has no portable secret-reference field. Store the value with the client's own secret/environment facility so the plugin MCP subprocess receives `CLOUDFLARE_API_TOKEN`. Do not write the API token into `${PLUGIN_DATA}` yourself; that directory is reserved here for the package-managed browser OAuth token store. Restart or reload the plugin if the client only snapshots environment at process launch, then verify one live API read.
+   - **Unknown host:** stop before writing. Ask where that client stores MCP environment secrets; never guess a Pi path.
+7. Destroy temporary copies. Report stored + verified **without printing the secret**.
 
 ## What success looks like
 
 - Exactly one active token under the expected name (list and check for duplicates — a failed first attempt often leaves one behind).
 - `modified_on` bumped, old secret rejected (spot-check one call with it only if exposure is suspected; otherwise just rotate wiring).
+- The active host can resolve the new token after a fresh MCP/session start and one live scoped read succeeds.
 - Never retry-loop the confirm dialog. One confirm, one capture.

package/skills/sandbox-migrate-to-next/SKILL.md

@@ -151,7 +151,7 @@ Delete transport settings entirely. Remove session APIs. Isolate users with **se
 
 ### Deploy cutover
 
-Staging/branch first. Production is **one** deploy of matching Worker + image:
+Validate a preview deployment first. Production is **one** deploy of matching Worker + image:
 
 ```sh
 npx wrangler deploy --containers-rollout=immediate