@flue/client 0.0.22 → 0.0.24

package/README.md

@@ -69,10 +69,23 @@ const summary = await flue.prompt('Summarize these test failures: ...', {
 
 Options: `result`, `model`
 
-### Properties
+## Proxies (Sandbox Mode)
 
-| Property       | Type                      | Description                             |
-| -------------- | ------------------------- | --------------------------------------- |
-| `flue.args`    | `Record<string, unknown>` | Workflow arguments passed by the runner |
-| `flue.secrets` | `Record<string, string>`  | Scoped secrets passed by the runner     |
-| `flue.branch`  | `string`                  | Working branch for commits              |
+In sandbox mode, the AI agent runs inside a sandbox container with no access to sensitive host credentials. Proxies let the sandbox talk to external services without leaking any actual credentials into the sandbox.
+
+Flue ships with built-in presets for popular services. Every proxy supports an access control policy (`policy`) option for advanced control over what the sandbox has access to do. Built-in levels like `'allow-read'` and `'allow-all'` cover common service-specific policy rules, and you can extend them with explicit allow/deny rules for fine-grained control:
+
+```ts
+import { anthropic, github } from '@flue/client/proxies';
+
+export const proxies = [
+  anthropic(),
+  github({
+    token: process.env.GH_TOKEN!,
+    policy: {
+      base: 'allow-read',
+      allow: [{ method: 'POST', path: '/repos/withastro/astro/issues/*/comments', limit: 1 }],
+    },
+  }),
+];
+```

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { i as ProxyService, n as ProxyPolicy, r as ProxyPresetResult, t as PolicyRule } from "./types-Ch4cwdD8.mjs";
+import { a as ProxyService, i as ProxyPresetResult, r as ProxyPolicy, t as PolicyRule } from "./types-DnTJOlQ7.mjs";
 import * as v from "valibot";
 
 //#region src/errors.d.ts
@@ -74,22 +74,34 @@ type FlueEvent = {
 declare function transformEvent(raw: any): FlueEvent | null;
 //#endregion
 //#region src/types.d.ts
-interface FlueOptions {
+interface FlueClientOptions {
   /** OpenCode server URL (default: 'http://localhost:48765'). */
   opencodeUrl?: string;
   /** Working directory (the repo root). */
   workdir: string;
-  /** Working branch for commits. */
-  branch?: string;
-  /** Workflow arguments. */
-  args?: Record<string, unknown>;
-  /** Proxy instructions to append to every skill/prompt call. */
-  proxyInstructions?: string[];
+  /** Proxy configs — instructions are extracted and appended to every skill/prompt call. */
+  proxies?: ProxyService[];
   /** Default model for skill/prompt invocations. */
   model?: {
     providerID: string;
     modelID: string;
   };
+  /**
+   * Custom fetch implementation for reaching the OpenCode server.
+   * Use this when the OpenCode server is not reachable via global fetch
+   * (e.g. from a Cloudflare Worker, route through sandbox.containerFetch).
+   *
+   * When omitted, the SDK's default fetch (globalThis.fetch) is used.
+   */
+  fetch?: (request: Request) => Promise<Response>;
+  /**
+   * Custom shell implementation for executing commands.
+   * Use this when child_process is not available (e.g. Cloudflare Workers)
+   * and commands should be routed through sandbox.exec() instead.
+   *
+   * When omitted, commands run via Node.js child_process.exec.
+   */
+  shell?: (command: string, options?: ShellOptions) => Promise<ShellResult>;
 }
 interface SkillOptions<S extends v.GenericSchema | undefined = undefined> {
   /** Key-value args serialized into the prompt. */
@@ -128,16 +140,13 @@ interface ShellResult {
 }
 //#endregion
 //#region src/flue.d.ts
-declare class Flue {
-  /** Working branch for commits. */
-  readonly branch: string;
-  /** Workflow arguments passed by the runner. */
-  readonly args: Record<string, unknown>;
+declare class FlueClient {
   private readonly workdir;
   private readonly proxyInstructions;
   private readonly model?;
   private readonly client;
-  constructor(options: FlueOptions);
+  private readonly shellFn?;
+  constructor(options: FlueClientOptions);
   /** Run a named skill with a result schema. */
   skill<S extends v.GenericSchema>(name: string, options: SkillOptions<S> & {
     result: S;
@@ -156,4 +165,4 @@ declare class Flue {
   close(): Promise<void>;
 }
 //#endregion
-export { Flue, type FlueEvent, type FlueOptions, type PolicyRule, type PromptOptions, type ProxyPolicy, type ProxyPresetResult, type ProxyService, type ShellOptions, type ShellResult, type SkillOptions, SkillOutputError, transformEvent };
+export { FlueClient, type FlueClientOptions, type FlueEvent, type PolicyRule, type PromptOptions, type ProxyPolicy, type ProxyPresetResult, type ProxyService, type ShellOptions, type ShellResult, type SkillOptions, SkillOutputError, transformEvent };

package/dist/index.mjs

@@ -326,9 +326,9 @@ function extractLastResultBlock(text) {
 //#endregion
 //#region src/skill.ts
 /** How often to poll and log progress (ms). */
-const POLL_INTERVAL = 5e3;
+const POLL_INTERVAL = 15e3;
 /** Max times we'll see 0 assistant messages before giving up. */
-const MAX_EMPTY_POLLS = 60;
+const MAX_EMPTY_POLLS = 20;
 /** Max time to poll before timing out (ms) - 45 minutes. */
 const MAX_POLL_TIME = 2700 * 1e3;
 /**
@@ -430,7 +430,7 @@ async function pollUntilIdle(client, sessionId, workdir, label, startTime) {
 			const parts = await fetchAllAssistantParts(client, sessionId, workdir);
 			if (parts.length === 0) {
 				emptyPolls++;
-				if (emptyPolls % 12 === 0) {
+				if (emptyPolls % 4 === 0) {
 					console.log(`[flue] ${label}: status result: ${JSON.stringify({
 						hasData: !!statusResult.data,
 						sessionIds: statusResult.data ? Object.keys(statusResult.data) : [],
@@ -455,7 +455,7 @@ async function pollUntilIdle(client, sessionId, workdir, label, startTime) {
 			}
 			return parts;
 		}
-		if (pollCount % 12 === 0) console.log(`[flue] ${label}: running (${elapsed}s)`);
+		if (pollCount % 4 === 0) console.log(`[flue] ${label}: running (${elapsed}s)`);
 	}
 }
 /**
@@ -478,33 +478,26 @@ function sleep(ms) {
 
 //#endregion
 //#region src/flue.ts
-var Flue = class {
-	/** Working branch for commits. */
-	branch;
-	/** Workflow arguments passed by the runner. */
-	args;
+var FlueClient = class {
 	workdir;
 	proxyInstructions;
 	model;
 	client;
+	shellFn;
 	constructor(options) {
-		this.branch = options.branch ?? "main";
-		this.args = options.args ?? {};
-		this.proxyInstructions = options.proxyInstructions ?? [];
+		this.proxyInstructions = options.proxies?.map((p) => p.instructions).filter((i) => !!i) ?? [];
 		this.workdir = options.workdir;
 		this.model = options.model;
+		this.shellFn = options.shell;
 		this.client = createOpencodeClient({
 			baseUrl: options.opencodeUrl ?? "http://localhost:48765",
-			directory: this.workdir
+			directory: this.workdir,
+			...options.fetch ? { fetch: options.fetch } : {}
 		});
 	}
 	async skill(name, options) {
 		const mergedOptions = {
 			...options,
-			args: this.args || options?.args ? {
-				...this.args,
-				...options?.args
-			} : void 0,
 			model: options?.model ?? this.model
 		};
 		return runSkill(this.client, this.workdir, name, mergedOptions, this.proxyInstructions);
@@ -527,14 +520,16 @@ var Flue = class {
 	}
 	/** Execute a shell command with scoped environment variables. */
 	async shell(command, options) {
-		return runShell(command, {
+		const mergedOptions = {
 			...options,
 			cwd: options?.cwd ?? this.workdir
-		});
+		};
+		if (this.shellFn) return this.shellFn(command, mergedOptions);
+		return runShell(command, mergedOptions);
 	}
 	/** Close the OpenCode client connection. */
 	async close() {}
 };
 
 //#endregion
-export { Flue, SkillOutputError, transformEvent };
+export { FlueClient, SkillOutputError, transformEvent };

package/dist/proxies/index.d.mts

@@ -1,23 +1,25 @@
-import { i as ProxyService, n as ProxyPolicy, r as ProxyPresetResult, t as PolicyRule } from "../types-Ch4cwdD8.mjs";
+import { a as ProxyService, i as ProxyPresetResult, n as ProxyFactory, r as ProxyPolicy, t as PolicyRule } from "../types-DnTJOlQ7.mjs";
 
 //#region src/proxies/anthropic.d.ts
 /**
  * Anthropic model provider proxy preset.
  *
- * Proxies requests to api.anthropic.com with the API key injected.
- * Reads ANTHROPIC_API_KEY from the environment by default.
- * Strips all non-allowlisted headers for security.
+ * Returns a ProxyFactory that, when called with `{ apiKey }`, produces a
+ * ProxyService proxying requests to api.anthropic.com with the API key
+ * injected. Strips all non-allowlisted headers for security.
  */
 declare function anthropic(opts?: {
-  apiKey?: string;
   policy?: string | ProxyPolicy;
-}): ProxyService;
+}): ProxyFactory<{
+  apiKey: string;
+}>;
 //#endregion
 //#region src/proxies/github.d.ts
 /**
  * GitHub proxy preset.
  *
- * Returns two `ProxyService` objects:
+ * Returns a ProxyFactory that, when called with `{ token }`, produces two
+ * ProxyService objects:
  * - `github-api`: unix socket proxy for REST/GraphQL API (api.github.com),
  *   used by the `gh` CLI and `curl`.
  * - `github-git`: TCP port proxy for git smart HTTP (github.com),
@@ -25,28 +27,48 @@ declare function anthropic(opts?: {
  *
  * Both share the same token and policy.
  */
-declare function github(opts: {
-  token: string;
+declare function github(opts?: {
   policy?: string | ProxyPolicy;
-}): ProxyService[];
+}): ProxyFactory<{
+  token: string;
+}>;
 /**
  * Body validation helpers for GitHub API requests.
  *
  * These return validator functions suitable for `PolicyRule.body`.
  */
 declare const githubBody: {
-  /** Validate an issue creation body. */issue(opts: {
-    titleMatch?: RegExp;
-    requiredLabels?: string[];
-  }): (body: unknown) => boolean; /** Validate a comment body. */
-  comment(opts: {
-    maxLength?: number;
-    pattern?: RegExp;
-  }): (body: unknown) => boolean; /** Validate a GraphQL request — restrict to queries only, or specific operations. */
-  graphql(opts?: {
+  /** Validate a GraphQL request — restrict to queries only, or specific operations. */graphql(opts?: {
     allowedOperations?: string[];
     denyMutations?: boolean;
   }): (body: unknown) => boolean;
 };
 //#endregion
-export { type PolicyRule, type ProxyPolicy, type ProxyPresetResult, type ProxyService, anthropic, github, githubBody };
+//#region src/proxies/policy.d.ts
+/**
+ * Shared policy evaluation for proxy requests.
+ *
+ * This is the canonical TypeScript implementation. The CLI's proxy-server.mjs
+ * has an identical zero-dependency copy (see packages/cli/src/sandbox/proxy-server.mjs).
+ */
+interface PolicyResult {
+  allowed: boolean;
+  reason: string;
+}
+/**
+ * Match a URL path against a glob-style pattern.
+ * `*` matches one path segment, `**` matches zero or more.
+ */
+declare function matchPath(pattern: string, path: string): boolean;
+declare function matchMethod(ruleMethod: string | string[], requestMethod: string): boolean;
+/**
+ * Evaluate the proxy policy for a request.
+ * Order: deny rules -> allow rules (with optional body + rate limits) -> base level.
+ *
+ * `ruleCounts` is optional — omit on Cloudflare where rate limits are not enforced.
+ * `body` validators on rules are skipped when not present (Cloudflare v1 stores
+ * policies without functions).
+ */
+declare function evaluatePolicy(method: string, path: string, parsedBody: unknown, policy: ProxyPolicy | null, ruleCounts?: Map<string, number>): PolicyResult;
+//#endregion
+export { type PolicyResult, type PolicyRule, type ProxyFactory, type ProxyPolicy, type ProxyPresetResult, type ProxyService, anthropic, evaluatePolicy, github, githubBody, matchMethod, matchPath };

package/dist/proxies/index.mjs

@@ -2,37 +2,45 @@
 /**
 * Anthropic model provider proxy preset.
 *
-* Proxies requests to api.anthropic.com with the API key injected.
-* Reads ANTHROPIC_API_KEY from the environment by default.
-* Strips all non-allowlisted headers for security.
+* Returns a ProxyFactory that, when called with `{ apiKey }`, produces a
+* ProxyService proxying requests to api.anthropic.com with the API key
+* injected. Strips all non-allowlisted headers for security.
 */
 function anthropic(opts) {
-	const apiKey = opts?.apiKey || process.env.ANTHROPIC_API_KEY;
-	if (!apiKey) throw new Error("anthropic() proxy requires ANTHROPIC_API_KEY. Set it in your environment or pass { apiKey } explicitly.");
-	return {
-		name: "anthropic",
-		target: "https://api.anthropic.com",
-		transform: (req) => {
-			const safe = [
-				"content-type",
-				"content-length",
-				"accept",
-				"anthropic-version",
-				"anthropic-beta",
-				"user-agent"
-			];
-			const filtered = {};
-			for (const key of safe) if (req.headers[key]) filtered[key] = req.headers[key];
-			filtered["x-api-key"] = apiKey;
-			return { headers: filtered };
-		},
-		policy: opts?.policy ?? "allow-all",
-		isModelProvider: true,
-		providerConfig: {
-			providerKey: "anthropic",
-			options: { apiKey: "sk-dummy-value-real-key-injected-by-proxy" }
-		}
+	const factory = (secrets) => {
+		const { apiKey } = secrets;
+		return {
+			name: "anthropic",
+			target: "https://api.anthropic.com",
+			headers: {
+				"x-api-key": apiKey,
+				host: "api.anthropic.com"
+			},
+			transform: (req) => {
+				const safe = [
+					"content-type",
+					"content-length",
+					"accept",
+					"anthropic-version",
+					"anthropic-beta",
+					"user-agent"
+				];
+				const filtered = {};
+				for (const key of safe) if (req.headers[key]) filtered[key] = req.headers[key];
+				filtered["x-api-key"] = apiKey;
+				return { headers: filtered };
+			},
+			policy: opts?.policy ?? "allow-all",
+			isModelProvider: true,
+			providerConfig: {
+				providerKey: "anthropic",
+				options: { apiKey: "sk-dummy-value-real-key-injected-by-proxy" }
+			}
+		};
 	};
+	factory.secretsMap = { apiKey: "ANTHROPIC_API_KEY" };
+	factory.proxyName = "anthropic";
+	return factory;
 }
 
 //#endregion
@@ -40,7 +48,8 @@ function anthropic(opts) {
 /**
 * GitHub proxy preset.
 *
-* Returns two `ProxyService` objects:
+* Returns a ProxyFactory that, when called with `{ token }`, produces two
+* ProxyService objects:
 * - `github-api`: unix socket proxy for REST/GraphQL API (api.github.com),
 *   used by the `gh` CLI and `curl`.
 * - `github-git`: TCP port proxy for git smart HTTP (github.com),
@@ -49,62 +58,70 @@ function anthropic(opts) {
 * Both share the same token and policy.
 */
 function github(opts) {
-	const resolvedPolicy = resolveGitHubPolicy(opts.policy ?? "read-only");
-	const denyResponse = ({ method, path, reason }) => ({
-		status: 403,
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify({
-			message: `Blocked by flue proxy policy: ${method} ${path} — ${reason}`,
-			documentation_url: "https://flue.dev/docs/proxy-policy"
-		})
-	});
-	return [{
-		name: "github-api",
-		target: "https://api.github.com",
-		headers: {
-			authorization: `token ${opts.token}`,
-			host: "api.github.com",
-			"user-agent": "flue-proxy"
-		},
-		policy: resolvedPolicy,
-		socket: true,
-		env: { GH_TOKEN: "proxy-placeholder" },
-		setup: ["gh config set http_unix_socket {{socketPath}} 2>/dev/null || true"],
-		instructions: ["The `gh` CLI is pre-configured with authentication.", "For GitHub API calls, prefer `gh api` over raw `curl`."].join(" "),
-		denyResponse
-	}, {
-		name: "github-git",
-		target: "https://github.com",
-		headers: {
-			authorization: `Basic ${Buffer.from(`x-access-token:${opts.token}`).toString("base64")}`,
-			"user-agent": "flue-proxy"
-		},
-		policy: resolvedPolicy,
-		setup: ["git config --global url.\"{{proxyUrl}}/\".insteadOf \"https://github.com/\"", "git config --global http.{{proxyUrl}}/.extraheader \"Authorization: Bearer proxy-placeholder\""],
-		denyResponse
-	}];
+	const factory = (secrets) => {
+		const { token } = secrets;
+		const resolvedPolicy = resolveGitHubPolicy(opts?.policy);
+		const denyResponse = ({ method, path, reason }) => ({
+			status: 403,
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				message: `Blocked by flue proxy policy: ${method} ${path} — ${reason}`,
+				documentation_url: "https://flue.dev/docs/proxy-policy"
+			})
+		});
+		return [{
+			name: "github-api",
+			target: "https://api.github.com",
+			headers: {
+				authorization: `token ${token}`,
+				host: "api.github.com",
+				"user-agent": "flue-proxy"
+			},
+			policy: resolvedPolicy,
+			socket: true,
+			env: { GH_TOKEN: "proxy-placeholder" },
+			setup: ["gh config set http_unix_socket {{socketPath}} 2>/dev/null || true"],
+			instructions: ["The `gh` CLI is pre-configured with authentication.", "For GitHub API calls, prefer `gh api` over raw `curl`."].join(" "),
+			denyResponse
+		}, {
+			name: "github-git",
+			target: "https://github.com",
+			headers: {
+				authorization: `Basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`,
+				"user-agent": "flue-proxy"
+			},
+			policy: resolvedPolicy,
+			setup: ["git config --global url.\"{{proxyUrl}}/\".insteadOf \"https://github.com/\"", "git config --global http.{{proxyUrl}}/.extraheader \"Authorization: Bearer proxy-placeholder\""],
+			denyResponse
+		}];
+	};
+	factory.secretsMap = { token: "GITHUB_TOKEN" };
+	factory.proxyName = "github";
+	return factory;
 }
 /**
-* Resolve GitHub-specific policy level names to concrete ProxyPolicy rules.
+* Resolve a GitHub policy into a concrete ProxyPolicy.
 *
-* Levels:
-* - 'read-only': GET/HEAD only (default)
-* - 'read-only+clone': GET/HEAD + git smart HTTP fetch (clone/pull)
-* - 'allow-all': everything allowed
+* Accepts a core policy level string ('allow-read', 'allow-all', 'deny-all')
+* or a ProxyPolicy object. Defaults to 'allow-read' if omitted.
+*
+* When the base is 'allow-read', GitHub-specific allow rules are prepended
+* so that the gh CLI (GraphQL queries) and git clone/fetch work out of the box.
+* Other base levels are used as-is.
 */
 function resolveGitHubPolicy(policy) {
-	if (typeof policy !== "string") return policy;
-	switch (policy) {
-		case "read-only": return {
-			default: "deny-non-safe",
-			allow: [{
-				method: "POST",
-				path: "/graphql",
-				body: githubBody.graphql()
-			}]
+	const base = typeof policy === "string" ? policy : policy?.base ?? "allow-read";
+	const userAllow = typeof policy === "object" ? policy.allow ?? [] : [];
+	const userDeny = typeof policy === "object" ? policy.deny ?? [] : [];
+	switch (base) {
+		case "allow-all":
+		case "deny-all": return {
+			base,
+			allow: userAllow,
+			deny: userDeny
 		};
-		case "read-only+clone": return {
-			default: "deny-non-safe",
+		default: return {
+			base: "allow-read",
 			allow: [
 				{
 					method: "POST",
@@ -118,11 +135,11 @@ function resolveGitHubPolicy(policy) {
 				{
 					method: "GET",
 					path: "/*/info/refs"
-				}
-			]
+				},
+				...userAllow
+			],
+			deny: userDeny
 		};
-		case "allow-all": return { default: "allow-all" };
-		default: throw new Error(`Unknown github() policy level: '${policy}'`);
 	}
 }
 /**
@@ -130,42 +147,123 @@ function resolveGitHubPolicy(policy) {
 *
 * These return validator functions suitable for `PolicyRule.body`.
 */
-const githubBody = {
-	issue(opts) {
-		return (body) => {
-			const b = body;
-			if (opts.titleMatch && !opts.titleMatch.test(b?.title ?? "")) return false;
-			if (opts.requiredLabels) {
-				const labels = (b?.labels ?? []).map((l) => typeof l === "string" ? l : l?.name);
-				if (!opts.requiredLabels.every((r) => labels.includes(r))) return false;
-			}
-			return true;
+const githubBody = { graphql(opts) {
+	return (body) => {
+		const b = body;
+		if (typeof b?.query !== "string") return false;
+		if (opts?.denyMutations !== false) {
+			const trimmed = b.query.replace(/\s+/g, " ").trim();
+			if (trimmed.startsWith("mutation") || /^\s*mutation\b/.test(trimmed)) return false;
+		}
+		if (opts?.allowedOperations) {
+			if (!b.operationName || !opts.allowedOperations.includes(b.operationName)) return false;
+		}
+		return true;
+	};
+} };
+
+//#endregion
+//#region src/proxies/policy.ts
+/**
+* Match a URL path against a glob-style pattern.
+* `*` matches one path segment, `**` matches zero or more.
+*/
+function matchPath(pattern, path) {
+	return matchParts(pattern.split("/").filter(Boolean), 0, path.split("/").filter(Boolean), 0);
+}
+function matchParts(pattern, pi, path, pai) {
+	while (pi < pattern.length && pai < path.length) {
+		if (pattern[pi] === "**") {
+			for (let skip = pai; skip <= path.length; skip++) if (matchParts(pattern, pi + 1, path, skip)) return true;
+			return false;
+		}
+		if (pattern[pi] === "*" || pattern[pi] === path[pai]) {
+			pi++;
+			pai++;
+		} else return false;
+	}
+	while (pi < pattern.length && pattern[pi] === "**") pi++;
+	return pi === pattern.length && pai === path.length;
+}
+function matchMethod(ruleMethod, requestMethod) {
+	if (ruleMethod === "*") return true;
+	if (Array.isArray(ruleMethod)) return ruleMethod.some((m) => m.toUpperCase() === requestMethod.toUpperCase());
+	return ruleMethod.toUpperCase() === requestMethod.toUpperCase();
+}
+/**
+* Evaluate the proxy policy for a request.
+* Order: deny rules -> allow rules (with optional body + rate limits) -> base level.
+*
+* `ruleCounts` is optional — omit on Cloudflare where rate limits are not enforced.
+* `body` validators on rules are skipped when not present (Cloudflare v1 stores
+* policies without functions).
+*/
+function evaluatePolicy(method, path, parsedBody, policy, ruleCounts) {
+	if (!policy) {
+		if ([
+			"GET",
+			"HEAD",
+			"OPTIONS"
+		].includes(method.toUpperCase())) return {
+			allowed: true,
+			reason: ""
 		};
-	},
-	comment(opts) {
-		return (body) => {
-			const b = body;
-			if (typeof b?.body !== "string") return false;
-			if (opts.maxLength && b.body.length > opts.maxLength) return false;
-			if (opts.pattern && !opts.pattern.test(b.body)) return false;
-			return true;
+		return {
+			allowed: false,
+			reason: "not allowed by default allow-read policy"
 		};
-	},
-	graphql(opts) {
-		return (body) => {
-			const b = body;
-			if (typeof b?.query !== "string") return false;
-			if (opts?.denyMutations !== false) {
-				const trimmed = b.query.replace(/\s+/g, " ").trim();
-				if (trimmed.startsWith("mutation") || /^\s*mutation\b/.test(trimmed)) return false;
-			}
-			if (opts?.allowedOperations) {
-				if (!b.operationName || !opts.allowedOperations.includes(b.operationName)) return false;
+	}
+	if (policy.deny) {
+		for (const rule of policy.deny) if (matchMethod(rule.method, method) && matchPath(rule.path, path)) {
+			if (rule.body === void 0 || rule.body(parsedBody) === true) return {
+				allowed: false,
+				reason: "matched deny rule"
+			};
+		}
+	}
+	if (policy.allow) for (let i = 0; i < policy.allow.length; i++) {
+		const rule = policy.allow[i];
+		if (matchMethod(rule.method, method) && matchPath(rule.path, path)) {
+			if (rule.body !== void 0 && rule.body(parsedBody) === false) continue;
+			if (rule.limit !== void 0 && ruleCounts) {
+				const key = `allow:${i}`;
+				const count = ruleCounts.get(key) || 0;
+				if (count >= rule.limit) return {
+					allowed: false,
+					reason: `limit reached (${count}/${rule.limit})`
+				};
+				ruleCounts.set(key, count + 1);
 			}
-			return true;
+			return {
+				allowed: true,
+				reason: ""
+			};
+		}
+	}
+	switch (policy.base || "allow-read") {
+		case "allow-all": return {
+			allowed: true,
+			reason: ""
+		};
+		case "deny-all": return {
+			allowed: false,
+			reason: "base policy: deny-all"
 		};
+		default:
+			if ([
+				"GET",
+				"HEAD",
+				"OPTIONS"
+			].includes(method.toUpperCase())) return {
+				allowed: true,
+				reason: ""
+			};
+			return {
+				allowed: false,
+				reason: "not allowed by allow-read policy"
+			};
 	}
-};
+}
 
 //#endregion
-export { anthropic, github, githubBody };
+export { anthropic, evaluatePolicy, github, githubBody, matchMethod, matchPath };

package/dist/{types-Ch4cwdD8.d.mts → types-DnTJOlQ7.d.mts}

@@ -63,14 +63,14 @@ interface ProxyService {
   /**
    * Access control policy for this proxy.
    *
-   * String shorthand: a named policy level defined by the preset.
-   * Object form: full control with default level + allow/deny rules.
+   * String shorthand: a core policy level ('allow-read', 'allow-all', 'deny-all').
+   * Object form: full control with base level + allow/deny rules.
    *
-   * When a string is provided, it is equivalent to { default: theString }.
+   * When a string is provided, it is equivalent to { base: theString }.
    *
-   * If omitted, defaults to 'read-only' (GET/HEAD only).
-   * Each preset defines what its policy levels mean — see the preset
-   * documentation for available levels.
+   * If omitted, defaults to 'allow-read' (GET/HEAD/OPTIONS only).
+   * Presets may extend the base level with additional allow rules
+   * appropriate for their service.
    */
   policy?: string | ProxyPolicy;
   /**
@@ -108,16 +108,22 @@ interface ProxyService {
 }
 interface ProxyPolicy {
   /**
-   * The base policy level. Preset-defined string that maps to a set of rules.
-   * Common levels: 'read-only', 'allow-all', 'deny-all'.
-   * Presets may define additional levels (e.g., 'read-only+clone' for GitHub).
+   * The base policy level that applies when no allow/deny rule matches.
+   *
+   * - `'allow-read'`: allow GET/HEAD/OPTIONS, deny everything else
+   * - `'allow-all'`: allow everything
+   * - `'deny-all'`: deny everything
+   *
+   * Presets may extend the base level with additional allow rules
+   * (e.g., the GitHub preset adds GraphQL query and git clone support
+   * on top of `'allow-read'`).
    */
-  default: string;
+  base: string;
   /**
    * Explicit allow rules. Evaluated after deny rules.
    * A request matching an allow rule is permitted (subject to rate limits).
    * If a request matches method + path but fails body validation, the rule
-   * does not match and evaluation continues to the next rule or default.
+   * does not match and evaluation continues to the next rule or base level.
    */
   allow?: PolicyRule[];
   /**
@@ -166,5 +172,18 @@ interface PolicyRule {
  * The CLI auto-flattens with proxies.flat().
  */
 type ProxyPresetResult = ProxyService | ProxyService[];
+/**
+ * A preset function with deferred secrets. Call without secrets to get
+ * a factory; call the factory with secrets to get resolved ProxyService(s).
+ *
+ * `secretsMap` maps each TSecrets key to its conventional env var name
+ * (e.g., `{ apiKey: 'ANTHROPIC_API_KEY' }`). The CLI uses this to
+ * auto-resolve secrets from `process.env`.
+ */
+interface ProxyFactory<TSecrets extends Record<string, string>> {
+  (secrets: TSecrets): ProxyService | ProxyService[];
+  secretsMap: { [K in keyof TSecrets]: string };
+  proxyName: string;
+}
 //#endregion
-export { ProxyService as i, ProxyPolicy as n, ProxyPresetResult as r, PolicyRule as t };
+export { ProxyService as a, ProxyPresetResult as i, ProxyFactory as n, ProxyPolicy as r, PolicyRule as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/client",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {