@jevvy/permissions 0.0.0

package/dist/engine.d.ts

@@ -0,0 +1,32 @@
+import type { JevClient, NoulAnswer } from "./core.ts";
+import type { ApprovalQuestions } from "./questions.ts";
+export type PermissionEffect = "allow" | "ask";
+export interface ResourceJudgment {
+    readonly resource: string;
+    readonly effect: PermissionEffect;
+    readonly model: string;
+    readonly answers: Readonly<Record<string, NoulAnswer>>;
+}
+export type PermissionReview = {
+    readonly effect: "allow";
+    readonly judgments: readonly ResourceJudgment[];
+} | {
+    readonly effect: "ask";
+    readonly reason: "judged" | "unavailable" | "empty";
+    readonly judgments: readonly ResourceJudgment[];
+};
+export interface PermissionRequest {
+    readonly action: string;
+    readonly resources: readonly string[];
+}
+export interface PermissionReviewer {
+    readonly review: (request: PermissionRequest, signal?: AbortSignal) => Promise<PermissionReview>;
+    readonly dispose: () => Promise<void>;
+}
+export interface PermissionReviewerOptions {
+    readonly questions?: ApprovalQuestions;
+    readonly timeoutMs?: number;
+    readonly cacheCapacity?: number;
+}
+export declare const permissionEffectOf: (answers: Readonly<Record<string, NoulAnswer>>, questions: ApprovalQuestions) => PermissionEffect;
+export declare const createPermissionReviewer: (client: JevClient, options?: PermissionReviewerOptions) => Promise<PermissionReviewer>;

package/dist/engine.js

@@ -0,0 +1,97 @@
+import { Cache, Duration, Effect, Exit } from "effect";
+import { defaultApprovalQuestions, toNoulQuestions } from "./questions.js";
+class JudgmentUnavailable extends Error {
+    name = "JudgmentUnavailable";
+}
+const answerPasses = (answer, question) => question.threshold.direction === "atMost"
+    ? answer <= question.threshold.value
+    : answer >= question.threshold.value;
+const validAnswer = (answer) => answer?.type === "noul" && Number.isFinite(answer.noul) && answer.noul >= 0 && answer.noul <= 1;
+export const permissionEffectOf = (answers, questions) => {
+    let effect = "allow";
+    for (const [key, question] of Object.entries(questions)) {
+        const answer = answers[key];
+        if (!validAnswer(answer))
+            throw new JudgmentUnavailable(`missing valid answer for ${key}`);
+        if (!answerPasses(answer.noul, question))
+            effect = "ask";
+    }
+    return effect;
+};
+const judgeResult = (resource, result, questions) => {
+    if (result.model.trim().length === 0)
+        throw new JudgmentUnavailable("missing model identifier");
+    return {
+        resource,
+        effect: permissionEffectOf(result.answers, questions),
+        model: result.model,
+        answers: result.answers,
+    };
+};
+const validateQuestions = (questions) => {
+    const entries = Object.entries(questions);
+    if (entries.length === 0)
+        throw new Error("at least one approval question is required");
+    for (const [key, question] of entries) {
+        if (key.length === 0)
+            throw new Error("approval question keys cannot be empty");
+        if (question.instructions.trim().length === 0)
+            throw new Error(`approval question ${key} has no instructions`);
+        if (!Number.isFinite(question.threshold.value) || question.threshold.value < 0 || question.threshold.value > 1) {
+            throw new Error(`approval question ${key} has an invalid threshold`);
+        }
+    }
+};
+const cacheKey = (action, resource) => `${action.length}:${action}${resource}`;
+const abortReason = (signal) => signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException("The operation was aborted", "AbortError");
+const isAborted = (signal) => signal?.aborted === true;
+export const createPermissionReviewer = async (client, options = {}) => {
+    const questions = options.questions ?? defaultApprovalQuestions;
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const capacity = options.cacheCapacity ?? 512;
+    validateQuestions(questions);
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error("timeoutMs must be positive");
+    if (!Number.isInteger(capacity) || capacity <= 0)
+        throw new Error("cacheCapacity must be a positive integer");
+    const noulQuestions = toNoulQuestions(questions);
+    const cache = await Effect.runPromise(Cache.makeWith((key) => {
+        const separator = key.indexOf(":");
+        const actionLength = Number(key.slice(0, separator));
+        const payload = key.slice(separator + 1);
+        const action = payload.slice(0, actionLength);
+        const resource = payload.slice(actionLength);
+        return Effect.tryPromise((signal) => client.evaluate({ state: { action, resource }, questions: noulQuestions }, signal)).pipe(Effect.timeout(timeoutMs), Effect.map((result) => judgeResult(resource, result, questions)), Effect.mapError((error) => new JudgmentUnavailable(String(error))));
+    }, {
+        capacity,
+        timeToLive: (exit) => Exit.isSuccess(exit) ? Duration.infinity : Duration.zero,
+    }));
+    return {
+        async review(request, signal) {
+            if (request.resources.length === 0)
+                return { effect: "ask", reason: "empty", judgments: [] };
+            const judgments = [];
+            for (const resource of request.resources) {
+                if (isAborted(signal))
+                    throw abortReason(signal);
+                try {
+                    const judgment = await Effect.runPromise(Cache.get(cache, cacheKey(request.action, resource)), signal === undefined ? undefined : { signal });
+                    judgments.push(judgment);
+                    if (judgment.effect === "ask")
+                        return { effect: "ask", reason: "judged", judgments };
+                }
+                catch {
+                    if (isAborted(signal))
+                        throw abortReason(signal);
+                    return { effect: "ask", reason: "unavailable", judgments };
+                }
+            }
+            return { effect: "allow", judgments };
+        },
+        async dispose() {
+            await client.dispose?.();
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./opencode/index.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { default } from "./opencode/index.js";

package/dist/opencode/credentials.d.ts

@@ -0,0 +1,33 @@
+import type { ProviderApiKeys, ProviderPreference } from "../config.ts";
+export declare const OPENCODE_INTEGRATION = "opencode";
+export type ProviderCredential = {
+    readonly kind: "zen";
+    readonly key: string;
+    readonly model: string;
+    readonly origin: "opencode" | "config";
+} | {
+    readonly kind: "typesafe";
+    readonly key: string;
+    readonly origin: "config";
+} | {
+    readonly kind: "unavailable";
+};
+export type StoredCredential = {
+    readonly type: "key";
+    readonly key: string;
+    readonly configuration?: Readonly<Record<string, string | number | boolean | readonly string[]>>;
+} | {
+    readonly type: "oauth";
+    readonly access: string;
+};
+export interface CredentialPorts<C> {
+    readonly activeIntegration: (id: string) => Promise<C | undefined>;
+    readonly resolveIntegration: (connection: C) => Promise<StoredCredential | undefined>;
+    readonly readEnv: (name: string) => string | undefined;
+}
+export interface ConnectionLike {
+    readonly kind: "credential" | "env";
+    readonly envName?: string;
+}
+export declare const credentialToken: (credential: StoredCredential | undefined) => string | undefined;
+export declare const resolveCredential: <C>(ports: CredentialPorts<C>, preference: ProviderPreference, describe: (connection: C) => ConnectionLike, apiKeys?: ProviderApiKeys) => Promise<ProviderCredential>;

package/dist/opencode/credentials.js

@@ -0,0 +1,44 @@
+import { DEFAULT_ZEN_MODEL } from "../core.js";
+import { Redacted } from "effect";
+export const OPENCODE_INTEGRATION = "opencode";
+export const credentialToken = (credential) => {
+    const token = credential?.type === "key" ? credential.key : credential?.access;
+    return token !== undefined && token.trim().length > 0 ? token : undefined;
+};
+const integrationCredential = async (ports, id, describe) => {
+    const connection = await ports.activeIntegration(id);
+    if (connection === undefined)
+        return undefined;
+    const like = describe(connection);
+    if (like.kind === "env" && like.envName !== undefined) {
+        const key = ports.readEnv(like.envName);
+        return key === undefined ? undefined : { type: "key", key };
+    }
+    const resolved = await ports.resolveIntegration(connection);
+    return credentialToken(resolved) === undefined ? undefined : resolved;
+};
+const zenCandidate = async (ports, describe, configuredKey) => {
+    const opencode = await integrationCredential(ports, OPENCODE_INTEGRATION, describe);
+    const opencodeToken = credentialToken(opencode);
+    if (opencodeToken !== undefined) {
+        return { kind: "zen", key: opencodeToken, model: DEFAULT_ZEN_MODEL, origin: "opencode" };
+    }
+    if (configuredKey !== undefined) {
+        return { kind: "zen", key: Redacted.value(configuredKey), model: DEFAULT_ZEN_MODEL, origin: "config" };
+    }
+    return { kind: "unavailable" };
+};
+const typeSafeCandidate = (configuredKey) => {
+    if (configuredKey !== undefined) {
+        return { kind: "typesafe", key: Redacted.value(configuredKey), origin: "config" };
+    }
+    return { kind: "unavailable" };
+};
+export const resolveCredential = async (ports, preference, describe, apiKeys = {}) => {
+    if (preference === "zen")
+        return zenCandidate(ports, describe, apiKeys.zen);
+    if (preference === "typesafe")
+        return typeSafeCandidate(apiKeys.typesafe);
+    const zen = await zenCandidate(ports, describe, apiKeys.zen);
+    return zen.kind === "unavailable" ? typeSafeCandidate(apiKeys.typesafe) : zen;
+};

package/dist/opencode/evaluate.d.ts

@@ -0,0 +1,18 @@
+import type { PermissionEvaluation } from "@opencode/plugin/promise/permission";
+import type { PermissionReviewer } from "../engine.ts";
+export interface EvaluationEvent {
+    readonly sessionID: string;
+    readonly action: string;
+    readonly resources: PermissionEvaluation["resources"];
+    readonly metadata?: PermissionEvaluation["metadata"];
+    effect: PermissionEvaluation["effect"];
+    message?: string;
+}
+export interface EvaluateOptions {
+    readonly report?: (entry: {
+        readonly effect: "allow" | "ask";
+        readonly reason: "judged" | "unavailable" | "empty";
+        readonly resources: number;
+    }) => void;
+}
+export declare const createEvaluate: (reviewer: PermissionReviewer | undefined, options: EvaluateOptions) => ((event: EvaluationEvent) => Promise<void>);

package/dist/opencode/evaluate.js

@@ -0,0 +1,20 @@
+import { Option, Schema } from "effect";
+const CommandMetadata = Schema.Struct({ command: Schema.NonEmptyString });
+const commandFrom = (metadata) => Schema.decodeUnknownOption(CommandMetadata)(metadata).pipe(Option.map(({ command }) => command.trim()), Option.filter((command) => command.length > 0), Option.getOrUndefined);
+export const createEvaluate = (reviewer, options) => async (event) => {
+    if (event.effect !== "ask" || event.action !== "shell" || reviewer === undefined)
+        return;
+    const command = commandFrom(event.metadata);
+    if (event.resources.length > 1 && command === undefined) {
+        options.report?.({ effect: "ask", reason: "unavailable", resources: event.resources.length });
+        return;
+    }
+    const resources = command === undefined
+        ? event.resources
+        : [...new Set([...event.resources, command])];
+    const review = await reviewer.review({ action: event.action, resources });
+    const reason = review.effect === "ask" ? review.reason : "judged";
+    options.report?.({ effect: review.effect, reason, resources: resources.length });
+    if (review.effect === "allow")
+        event.effect = "allow";
+};

package/dist/opencode/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/opencode/index.js

@@ -0,0 +1,91 @@
+import { createTypeSafeClient, createZenClient, DEFAULT_TYPESAFE_MODEL } from "../core.js";
+import { Plugin } from "@opencode/plugin";
+import { Effect } from "effect";
+import { loadJevvyConfig } from "../config.js";
+import { createPermissionReviewer } from "../engine.js";
+import { createEvaluate } from "./evaluate.js";
+import { credentialToken, OPENCODE_INTEGRATION, resolveCredential, } from "./credentials.js";
+const describeConnection = (connection) => connection.type === "env"
+    ? { kind: "env", envName: connection.name }
+    : { kind: "credential" };
+const storedCredentialFrom = (credential) => {
+    if (credential?.type === "key") {
+        return { type: "key", key: credential.key, configuration: credential.configuration };
+    }
+    if (credential?.type === "oauth")
+        return { type: "oauth", access: credential.access };
+    return undefined;
+};
+export default Plugin.define({
+    id: "jevvy.permissions",
+    async setup(ctx) {
+        const permissionConfig = await Effect.runPromise(loadJevvyConfig());
+        if (permissionConfig.kind === "invalid") {
+            console.warn("[jevvy] jevvy.jsonc failed validation, auto-approval is disabled", permissionConfig.message);
+        }
+        const ports = {
+            activeIntegration: (id) => ctx.integration.connection.active(id),
+            resolveIntegration: async (connection) => {
+                try {
+                    return storedCredentialFrom(await ctx.integration.connection.resolve(connection));
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            readEnv: (name) => process.env[name],
+        };
+        const apiKeys = permissionConfig.kind === "invalid" ? {} : permissionConfig.apiKeys;
+        const provider = permissionConfig.kind === "invalid" ? "auto" : permissionConfig.provider;
+        const credential = await resolveCredential(ports, provider, describeConnection, apiKeys);
+        let client;
+        if (credential.kind === "typesafe") {
+            client = createTypeSafeClient(credential.key);
+        }
+        if (credential.kind === "zen") {
+            if (credential.origin === "opencode") {
+                client = {
+                    async evaluate(request, signal) {
+                        const connection = await ctx.integration.connection.active(OPENCODE_INTEGRATION);
+                        const stored = connection === undefined
+                            ? undefined
+                            : storedCredentialFrom(await ctx.integration.connection.resolve(connection));
+                        const token = credentialToken(stored);
+                        if (token === undefined)
+                            throw new Error("OpenCode login is unavailable");
+                        return createZenClient(token, credential.model).evaluate(request, signal);
+                    },
+                };
+            }
+            else {
+                client = createZenClient(credential.key, credential.model);
+            }
+        }
+        const questions = permissionConfig.kind === "custom" ? permissionConfig.questions : undefined;
+        const reviewer = client === undefined || permissionConfig.kind === "invalid"
+            ? undefined
+            : await createPermissionReviewer(client, { questions });
+        if (client === undefined && permissionConfig.kind !== "invalid") {
+            console.warn("[jevvy] no provider credential, native permission prompts remain unchanged");
+        }
+        const evaluate = createEvaluate(reviewer, {
+            report: (entry) => console.info("[jevvy] permission review", entry),
+        });
+        const permissions = await ctx.permission.hook("evaluate", evaluate);
+        let model;
+        if (credential.kind === "zen")
+            model = credential.model;
+        if (credential.kind === "typesafe")
+            model = DEFAULT_TYPESAFE_MODEL;
+        console.info("[jevvy] loaded", {
+            provider: credential.kind,
+            model,
+            questions: permissionConfig.kind === "custom" ? "custom" : "calibrated-defaults",
+            autoApproval: reviewer === undefined ? "disabled" : "enabled",
+        });
+        return async () => {
+            await permissions.dispose();
+            await reviewer?.dispose();
+        };
+    },
+});

package/dist/questions.d.ts

@@ -0,0 +1,64 @@
+import type { NoulQuestion } from "./core.ts";
+export interface ApprovalThreshold {
+    readonly direction: "atLeast" | "atMost";
+    readonly value: number;
+}
+export interface ApprovalQuestion extends NoulQuestion {
+    readonly threshold: ApprovalThreshold;
+}
+export type ApprovalQuestions = Readonly<Record<string, ApprovalQuestion>>;
+/**
+ * The shipped inquiry set is calibrated as one unit with its thresholds and
+ * pinned models. Rewording or overriding any entry creates a custom policy.
+ */
+export declare const defaultApprovalQuestions: {
+    harmful: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            false: string;
+            true: string;
+        };
+        threshold: {
+            direction: "atMost";
+            value: number;
+        };
+    };
+    sensitive: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            false: string;
+            true: string;
+        };
+        threshold: {
+            direction: "atMost";
+            value: number;
+        };
+    };
+    untrusted: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            false: string;
+            true: string;
+        };
+        threshold: {
+            direction: "atMost";
+            value: number;
+        };
+    };
+    obscured: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            false: string;
+            true: string;
+        };
+        threshold: {
+            direction: "atMost";
+            value: number;
+        };
+    };
+};
+export declare const toNoulQuestions: (questions: ApprovalQuestions) => Record<string, NoulQuestion>;

package/dist/questions.js

@@ -0,0 +1,53 @@
+/**
+ * The shipped inquiry set is calibrated as one unit with its thresholds and
+ * pinned models. Rewording or overriding any entry creates a custom policy.
+ */
+export const defaultApprovalQuestions = {
+    harmful: {
+        type: "noul",
+        instructions: "How likely is executing this shell command exactly as written to cause meaningful harm that a person should review first? Count destructive or hard-to-reverse changes, including deleting files or source-control state and discarding uncommitted work, as harm. Also count security weakening, privileged system changes, publishing or deploying, substantial cost, and disruption to other users or services. Ordinary read-only commands, common shell builtins, and reversible local development bookkeeping are not harm.",
+        criteria: {
+            false: "Routine and harmless to execute without human review",
+            true: "Meaningfully harmful or consequential enough to require human review",
+        },
+        threshold: { direction: "atMost", value: 0.35 },
+    },
+    sensitive: {
+        type: "noul",
+        instructions: "How likely does this shell command itself clearly target credentials, private data, or security-sensitive material for exposure, transmission, printing, copying, or weakened protection? Do not infer sensitivity merely because a command reads ordinary source files, repository state, paths, or public remote metadata. Score high only when the command or a conventional target indicates sensitive material.",
+        criteria: {
+            false: "No credible risk to credentials, private data, or security-sensitive material",
+            true: "Credible risk of exposing or weakening protection for sensitive material",
+        },
+        threshold: { direction: "atMost", value: 0.5 },
+    },
+    untrusted: {
+        type: "noul",
+        instructions: "How likely is this shell command to execute code that is fetched, installed, generated, encoded, or otherwise not already present as a trusted local program? Include package installation hooks, pip or npm installs, fetched scripts, and decoded payload execution. Merely downloading data or running an ordinary installed command is not untrusted code execution.",
+        criteria: {
+            false: "Does not execute newly obtained or concealed code",
+            true: "Executes code that is newly obtained, installed, generated, or concealed",
+        },
+        threshold: { direction: "atMost", value: 0.5 },
+    },
+    obscured: {
+        type: "noul",
+        instructions: "How likely is the command's consequential behavior obscured or difficult to determine from the command itself, including encoded payloads, indirect execution, fetched code execution, shell tricks, or misleading construction? Ordinary flags, variables, pipes, familiar shell builtins such as true, and scripts with clear behavior are not obscured merely because they are terse or complex.",
+        criteria: {
+            false: "Consequential behavior is clear enough to judge from the command",
+            true: "Consequential behavior is hidden, indirect, or materially uncertain",
+        },
+        threshold: { direction: "atMost", value: 0.5 },
+    },
+};
+export const toNoulQuestions = (questions) => {
+    const result = {};
+    for (const [key, question] of Object.entries(questions)) {
+        result[key] = {
+            type: "noul",
+            instructions: question.instructions,
+            criteria: question.criteria,
+        };
+    }
+    return result;
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@jevvy/permissions",
+  "version": "0.0.0",
+  "description": "Auto-approve shell permission requests that Jevvy judges harmless",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/PanAchy/jevvy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PanAchy/jevvy.git",
+    "directory": "packages/permissions"
+  },
+  "bugs": {
+    "url": "https://github.com/PanAchy/jevvy/issues"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "permissions",
+    "agent",
+    "jev"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "jevvy-calibrate": "bin/jevvy-calibrate.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "scripts": {
+    "prebuild": "npm run build --workspace=@jevvy/core && node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.build.json && esbuild src/core.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/core.js && node ../../scripts/copy-calibration-assets.mjs",
+    "prepack": "npm run build && node ../../scripts/package-readme.mjs prepare",
+    "postpack": "node ../../scripts/package-readme.mjs clean"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/platform-node-shared": "4.0.0-rc.112",
+    "@opencode/client": "2.0.8",
+    "@opencode/plugin": "2.0.8",
+    "effect": "4.0.0-rc.112",
+    "jsonc-parser": "^3.3.1"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}