opencode-collaboration 0.2.3

package/dist/permissions.js

@@ -0,0 +1,194 @@
+/**
+ * Auto-resolve permission requests that originate from a peer-triggered
+ * turn, modeled after Claude Code's per-source permission modes.
+ *
+ * A turn counts as peer-triggered when the user message that started it was
+ * injected by this plugin — detectable via the `peerMessage: true` metadata
+ * stamped on the injected part (see delivery.ts). Permission requests point
+ * at the *assistant* message holding the tool call, so the lookup walks up
+ * via parentID to the originating user message before checking its parts.
+ *
+ * Mechanism: opencode 1.18 does not invoke the plugin SDK's `permission.ask`
+ * hook, but it publishes permission request events on the bus and exposes a
+ * reply endpoint — the same pair the TUI uses. The plugin listens for
+ * `permission.v2.asked` (and the legacy `permission.asked`) and replies
+ * "once" (allow) or "reject" (deny) when the requesting turn is
+ * peer-triggered. Local user turns get no reply and fall through to
+ * opencode's normal prompt flow untouched.
+ */
+const CACHE_CAP = 200;
+/** Assistant message -> its parent user message; 4 hops is generous. */
+const MAX_HOPS = 4;
+function flattenedPermissionText(props) {
+    const values = [];
+    const visit = (value, depth) => {
+        if (depth > 3 || value == null)
+            return;
+        if (typeof value === "string")
+            values.push(value);
+        else if (Array.isArray(value))
+            for (const item of value)
+                visit(item, depth + 1);
+        else if (typeof value === "object")
+            for (const item of Object.values(value))
+                visit(item, depth + 1);
+    };
+    visit(props, 0);
+    return values.join("\n").toLowerCase();
+}
+/**
+ * Requests in these categories always remain under OpenCode's native policy/UI.
+ *
+ * This is a best-effort denylist, not a security boundary: it matches on the
+ * flattened event text, so a determined peer message can phrase a request to
+ * avoid these patterns (e.g. `npm config set` never names `.npmrc`). Treat
+ * `peerPermissions: "allow"` as fully trusting your peers; use "ask" for
+ * anything sensitive.
+ */
+export function isProtectedPermission(props) {
+    const permission = String(props.permission ?? props.action ?? props.type ?? "").toLowerCase();
+    const text = flattenedPermissionText(props);
+    if (permission === "permission" || /permission[ _.-]*(?:escalat|config|rule)/.test(text))
+        return true;
+    return /(?:^|[\\/\s])agents\.md(?:$|\s)/i.test(text) ||
+        /(?:^|[\\/\s])(?:opencode(?:\.jsonc?)?|\.opencode)(?:$|[\\/\s])/i.test(text) ||
+        /(?:^|[\\/\s])(?:\.env(?:\.[^\s\\/]*)?|credentials?|secrets?|\.npmrc|\.pypirc|\.netrc|\.gitconfig)(?:$|\s)/i.test(text) ||
+        /(?:^|[\\/\s])(?:\.aws|\.ssh|\.gnupg|\.kube|\.docker)[\\/]/i.test(text) ||
+        // shell startup / persistence paths
+        /(?:^|[\\/\s])(?:\.zshrc|\.zshenv|\.zprofile|\.bashrc|\.bash_profile|\.bash_login|\.profile|config\.fish)(?:$|\s)/i.test(text) ||
+        /(?:^|[\\/\s])(?:launchagents|launchdaemons)[\\/]/i.test(text) ||
+        /(?:^|\s)(?:crontab|visudo)(?:\s|$)/i.test(text) ||
+        /\/(?:etc|private\/etc)\/(?:sudoers|crontab|cron\.)/i.test(text);
+}
+export function PeerPermissions(opts) {
+    // messageID -> whether that message's turn is peer-triggered. Verdicts are
+    // stable per message, and one turn typically raises several permission
+    // requests against the same messageID.
+    const turnCache = new Map();
+    // permission request IDs already replied to (both "permission.asked" and
+    // "permission.updated" may fire for one request)
+    const replied = new Set();
+    async function fetchMessage(sessionID, messageID) {
+        const res = await opts.client.session.message({
+            path: { id: sessionID, messageID },
+        });
+        const data = res.data;
+        if (!data)
+            return null;
+        return {
+            role: data.info?.role,
+            parentID: data.info?.parentID,
+            isPeer: Boolean(data.parts?.some((p) => Boolean(p.metadata?.peerMessage))),
+        };
+    }
+    async function isPeerTurn(sessionID, messageID) {
+        const key = `${sessionID}:${messageID}`;
+        const hit = turnCache.get(key);
+        if (hit !== undefined)
+            return hit;
+        let verdict = false;
+        let transient = false;
+        try {
+            let cursor = messageID;
+            for (let hop = 0; cursor && hop < MAX_HOPS; hop++) {
+                const view = await fetchMessage(sessionID, cursor);
+                if (!view) {
+                    // Message not retrievable yet (event raced storage) — the verdict
+                    // is not stable, so do not cache it.
+                    transient = true;
+                    break;
+                }
+                if (view.isPeer) {
+                    verdict = true;
+                    break;
+                }
+                if (view.role === "user" || !view.parentID)
+                    break;
+                cursor = view.parentID;
+            }
+        }
+        catch (err) {
+            // Message gone, server unreachable, ... — stay out of the way.
+            await opts.logger("debug", "peer-message lookup failed; leaving permission to default", {
+                error: String(err),
+                sessionID,
+                messageID,
+            });
+            return false; // not cached: a transient failure may succeed next time
+        }
+        if (transient)
+            return false; // not cached: re-evaluate on the next event
+        if (turnCache.size >= CACHE_CAP) {
+            const oldest = turnCache.keys().next().value;
+            if (oldest !== undefined)
+                turnCache.delete(oldest);
+        }
+        turnCache.set(key, verdict);
+        return verdict;
+    }
+    return {
+        async handleEvent(event) {
+            if (event.type !== "permission.v2.asked" && event.type !== "permission.asked")
+                return;
+            const mode = opts.mode();
+            if (mode === "ask")
+                return;
+            const props = event.properties ?? {};
+            const permissionID = props.id;
+            const sessionID = props.sessionID;
+            // v2 events carry the requesting tool call in `source`; legacy events
+            // (and the SSE compat mapping) use `messageID` / `tool.messageID`.
+            const source = props.source;
+            const tool = props.tool;
+            const messageID = (source?.messageID ?? tool?.messageID ?? props.messageID);
+            if (!permissionID || !sessionID || !messageID)
+                return;
+            if (replied.has(permissionID))
+                return;
+            if (!(await isPeerTurn(sessionID, messageID)))
+                return;
+            if (mode === "allow" && isProtectedPermission(props)) {
+                await opts.logger("warn", "protected peer permission left to OpenCode policy", {
+                    permission: props.permission ?? props.action ?? props.type,
+                    sessionID,
+                    permissionID,
+                });
+                return;
+            }
+            replied.add(permissionID);
+            if (replied.size > CACHE_CAP) {
+                const oldest = replied.values().next().value;
+                if (oldest !== undefined)
+                    replied.delete(oldest);
+            }
+            const response = mode === "deny" ? "reject" : "once";
+            try {
+                const client = opts.client;
+                if (typeof client.postSessionIdPermissionsPermissionId !== "function") {
+                    await opts.logger("warn", "permission reply endpoint unavailable in this SDK");
+                    return;
+                }
+                // invoked as a method: the SDK class needs its `this` binding
+                await client.postSessionIdPermissionsPermissionId({
+                    path: { id: sessionID, permissionID },
+                    body: { response },
+                    query: { directory: opts.directory },
+                });
+                await opts.logger("info", `auto-${mode} permission in peer-triggered turn`, {
+                    permission: props.action ?? props.type,
+                    title: props.title,
+                    sessionID,
+                    permissionID,
+                });
+            }
+            catch (err) {
+                replied.delete(permissionID); // allow a retry on the next event
+                await opts.logger("warn", "failed to auto-resolve permission", {
+                    error: String(err),
+                    sessionID,
+                    permissionID,
+                });
+            }
+        },
+    };
+}

package/dist/queue.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Endpoint-scoped durable delivery queue and held inbox.
+ */
+import type { ResolvedConfig } from "./config.js";
+import type { HeldMessage, InboundMessage, Logger, PeerAcknowledgementV2, ReceiveStatus } from "./types.js";
+export declare function stableSpoolEndpointId(directory: string): string;
+export declare function stableSessionEndpointId(sessionId: string): string;
+/**
+ * True when the session's durable spool holds any records — undelivered
+ * (queued/held/inflight) or delivered (done, retained 24h for dedupe).
+ * Startup adopts exactly these sessions (plus snapshot-busy ones): pending
+ * work must resume, and done records must load or a post-restart retry would
+ * deliver a duplicate. Everything else stays unpublished until real activity.
+ */
+export declare function hasSpoolRecords(config: ResolvedConfig, sessionId: string): boolean;
+export declare function createSessionMessageQueue(opts: {
+    config: ResolvedConfig;
+    sessionId: string;
+    logger: Logger;
+}): QueueInstance;
+export declare function createProcessMessageQueue(opts: {
+    config: ResolvedConfig;
+    directory: string;
+    logger: Logger;
+}): QueueInstance;
+export interface QueueOptions {
+    /** Logical receiver identity; Task 2 supplies one value per session endpoint. */
+    endpointId?: string;
+    maxQueue: number;
+    maxHeld: number;
+    /** Held messages expire after five minutes unless explicitly configured otherwise. */
+    heldExpiryMs?: number;
+    /** Short same-sender/content debounce window. */
+    debounceMs?: number;
+    inboxFile: string;
+    logger: Logger;
+}
+export interface QueueInstance {
+    /** Returns false when the queue is full. */
+    enqueue: (msg: InboundMessage) => boolean;
+    drain: () => InboundMessage[];
+    /** Mark a flushed batch as delivered and return durable final acknowledgements. */
+    complete: (messages: InboundMessage[]) => Promise<PeerAcknowledgementV2[]>;
+    /** Return a failed delivery batch from inflight to the front of the queue. */
+    requeue: (messages: InboundMessage[]) => Promise<void>;
+    /** Returns a durable duplicate acknowledgement when this sender/message pair already exists. */
+    duplicateAcknowledgement: (msg: InboundMessage) => PeerAcknowledgementV2 | null;
+    /** The original receiver state returned for an idempotent retry. */
+    existingStatus: (msg: InboundMessage) => ReceiveStatus | null;
+    isDebounced: (msg: InboundMessage) => boolean;
+    /** Refuse an inbound message and retain its final acknowledgement for deduplication. */
+    refuse: (msg: InboundMessage) => Promise<PeerAcknowledgementV2>;
+    pending: () => InboundMessage[];
+    size: () => number;
+    hold: (msg: InboundMessage) => Promise<boolean>;
+    held: () => HeldMessage[];
+    /** Move expired held records to done and return their final acknowledgements. */
+    expireHeld: () => Promise<PeerAcknowledgementV2[]>;
+    /** Final outcomes that still need to be returned to their sender. */
+    pendingAcknowledgements: () => PeerAcknowledgementV2[];
+    /** Durably record successful ACK transport so restarts do not resend forever. */
+    markAcknowledgementSent: (ack: PeerAcknowledgementV2) => Promise<void>;
+    /** Accept by 1-based index or "all"; returns the messages moved to the queue. */
+    acceptHeld: (which: number | "all") => Promise<HeldMessage[]>;
+    dropHeld: (which: number | "all") => Promise<number>;
+    loadHeld: () => Promise<void>;
+}
+export interface SpoolMigrationResult {
+    migrated: number;
+    deduplicated: number;
+    quarantined: number;
+    sourceEndpointId: string;
+    targetEndpointId: string;
+}
+/**
+ * Move Task 1's directory-scoped spool into Task 2's compatibility session.
+ * Individual renames are atomic and the operation is restart-safe. Both
+ * endpoint locks are acquired in endpoint-ID order so concurrent recovery
+ * cannot deadlock or race normal queue state transitions.
+ */
+export declare function migrateWorkspaceSpool(opts: {
+    config: ResolvedConfig;
+    directory: string;
+    targetSessionId: string;
+    logger: Logger;
+}): Promise<SpoolMigrationResult>;
+export declare function MessageQueue(opts: QueueOptions): QueueInstance;
+/** Per-key sliding-window rate limiter. */
+export declare function RateLimiter(limitPerMin: number): (key: string) => boolean;