@mirrowel/opencode-souk 0.1.0

package/dist/index.js

@@ -0,0 +1,303 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tool } from "@opencode-ai/plugin/tool";
+import { debugLog, loadSidecarSafe, personalityDescription, RegistryItem as RegistryItemSchema, splitModelRef } from "./config.js";
+import { nativeInstall, previewNativeInstall, scopeLabel } from "./install.js";
+import { loadRegistry } from "./registry.js";
+const KAF_PLAN = "kāf-plan";
+const KAF_ACTION = "kāf-action";
+const ACTION_TOOL = "souk_request_action";
+const REGISTRY_SEARCH_TOOL = "souk_registry_search";
+const NATIVE_PREVIEW_TOOL = "souk_native_preview";
+const NATIVE_INSTALL_TOOL = "souk_native_install";
+const plugin = async ({ client }) => {
+    return {
+        async config(config) {
+            installSoukSkillPath(config);
+            installKafAgents(config);
+            installToolPermissions(config);
+        },
+        tool: {
+            [ACTION_TOOL]: tool({
+                description: "Kāf-only tool. Ask the user yes/no before switching a Souk Forge session from plan mode to action mode. Include security risks and planned writes/actions.",
+                args: {
+                    plan: tool.schema.string().describe("The approved plan Kāf wants to execute."),
+                    security_risks: tool.schema.array(tool.schema.string()).describe("Security risks the user must review before action mode."),
+                    planned_actions: tool.schema.array(tool.schema.string()).describe("Concrete writes, installs, commands, or config changes planned."),
+                },
+                async execute(args, context) {
+                    if (context.agent !== KAF_PLAN && context.agent !== KAF_ACTION) {
+                        return {
+                            title: "Souk action denied",
+                            output: "This tool is exclusive to Kāf Forge agents and cannot be used by this agent.",
+                        };
+                    }
+                    if (context.agent === KAF_ACTION) {
+                        return {
+                            title: "Already in action mode",
+                            output: "This Forge session is already using Kāf action mode. Continue executing only the approved plan.",
+                        };
+                    }
+                    const risks = args.security_risks.length ? args.security_risks : ["No specific risks were supplied. Treat this as incomplete and continue planning if unsure."];
+                    const actions = args.planned_actions.length ? args.planned_actions : ["No concrete actions were supplied. Do not proceed without a concrete plan."];
+                    const summary = [
+                        "Kāf is asking to switch this Souk Forge session from plan mode to action mode.",
+                        "",
+                        "Security risks:",
+                        ...risks.map((risk) => `- ${risk}`),
+                        "",
+                        "Planned actions:",
+                        ...actions.map((action) => `- ${action}`),
+                        "",
+                        "The souk can make mistakes. Approve only if the plan and risks are acceptable.",
+                    ].join("\n");
+                    try {
+                        await context.ask({
+                            permission: ACTION_TOOL,
+                            patterns: ["Switch Kāf Forge session to action mode"],
+                            always: [],
+                            metadata: {
+                                title: "Approve Kāf action mode?",
+                                summary,
+                                risks,
+                                actions,
+                            },
+                        });
+                    }
+                    catch {
+                        return {
+                            title: "Action mode not approved",
+                            output: [
+                                "The user chose no. Nothing changed.",
+                                "Continue planning in Kāf plan mode. Address the user's concerns, refine the plan, and propose switching again only when appropriate.",
+                            ].join("\n"),
+                        };
+                    }
+                    queueActionContinuation(client, context.sessionID, args.plan, risks, actions);
+                    return {
+                        title: "Kāf action approved",
+                        output: "The user approved action mode. A same-session Kāf action continuation has been queued. Execute only the approved plan and keep asking before risky writes.",
+                    };
+                },
+            }),
+            [REGISTRY_SEARCH_TOOL]: tool({
+                description: "Kāf-only read-only tool. Search Souk's deduped registry cache/source results and return combo item metadata with all source provenance.",
+                args: {
+                    query: tool.schema.string().describe("Search text. Matches name, description, kind, tags, source, aliases, repo URL, and install specs."),
+                    limit: tool.schema.number().int().min(1).max(50).default(10).describe("Maximum result count."),
+                    refresh: tool.schema.boolean().default(false).describe("Fetch sources before searching instead of using cache."),
+                },
+                async execute(args, context) {
+                    if (!isKaf(context.agent))
+                        return deniedTool(REGISTRY_SEARCH_TOOL);
+                    const loaded = loadSidecarSafe();
+                    const cache = await loadRegistry(loaded.config, { force: args.refresh });
+                    const terms = args.query.toLowerCase().split(/\s+/).filter(Boolean);
+                    const results = cache.items.filter((item) => terms.every((term) => registryHaystack(item).includes(term))).slice(0, args.limit);
+                    return {
+                        title: `Souk registry search: ${results.length} result(s)`,
+                        output: JSON.stringify({ fetchedAt: cache.fetchedAt, sourceStatus: cache.sourceStatus, results }, null, 2),
+                    };
+                },
+            }),
+            [NATIVE_PREVIEW_TOOL]: tool({
+                description: "Kāf-only read-only tool. Preview Souk deterministic native install actions for selected registry item JSON and scope.",
+                args: nativeToolArgs(),
+                async execute(args, context) {
+                    if (!isKaf(context.agent))
+                        return deniedTool(NATIVE_PREVIEW_TOOL);
+                    const loaded = loadSidecarSafe();
+                    const scope = parseToolScope(args.scope_kind, args.project_path, context);
+                    const items = parseToolItems(args.items_json);
+                    const preview = await previewNativeInstall(items, scope, loaded.config.install);
+                    return {
+                        title: `Souk native preview: ${preview.supported ? "supported" : "unsupported"}`,
+                        output: [`Scope: ${scopeLabel(scope)}`, "", preview.summary, "", "Warnings:", ...preview.warnings.map((warning) => `- ${warning}`)].join("\n"),
+                        metadata: { supported: preview.supported, warnings: preview.warnings },
+                    };
+                },
+            }),
+            [NATIVE_INSTALL_TOOL]: tool({
+                description: "Kāf action-mode-only tool. Execute Souk deterministic native install actions for approved registry item JSON and scope. Prefer this over manual config edits for supported items.",
+                args: nativeToolArgs(),
+                async execute(args, context) {
+                    if (context.agent !== KAF_ACTION) {
+                        return {
+                            title: "Souk native install denied",
+                            output: "souk_native_install is only available to Kāf action mode after the user approves souk_request_action. In plan mode, use souk_native_preview instead.",
+                        };
+                    }
+                    const loaded = loadSidecarSafe();
+                    const scope = parseToolScope(args.scope_kind, args.project_path, context);
+                    const items = parseToolItems(args.items_json);
+                    const preview = await previewNativeInstall(items, scope, loaded.config.install);
+                    await context.ask({
+                        permission: NATIVE_INSTALL_TOOL,
+                        patterns: [`Native install ${items.length} item(s) to ${scopeLabel(scope)}`],
+                        always: [],
+                        metadata: { title: "Approve Souk native install?", scope: scopeLabel(scope), summary: preview.summary, warnings: preview.warnings },
+                    });
+                    const result = await nativeInstall({}, items, scope, {
+                        confirm: async (title, message) => {
+                            await context.ask({ permission: NATIVE_INSTALL_TOOL, patterns: [title], always: [], metadata: { title, summary: message } });
+                            return true;
+                        },
+                    }, loaded.config.install);
+                    return {
+                        title: "Souk native install result",
+                        output: ["Installed:", ...result.installed.map((line) => `- ${line}`), "", "Failed:", ...result.failed.map((line) => `- ${line}`)].join("\n"),
+                        metadata: result,
+                    };
+                },
+            }),
+        },
+    };
+};
+function nativeToolArgs() {
+    return {
+        items_json: tool.schema.string().describe("JSON array of Souk RegistryItem objects, usually copied from souk_registry_search or the Forge prompt selected items."),
+        scope_kind: tool.schema.enum(["global", "project"]).describe("Install scope."),
+        project_path: tool.schema.string().optional().describe("Project root for project scope. Defaults to current worktree when omitted."),
+    };
+}
+function isKaf(agent) {
+    return agent === KAF_PLAN || agent === KAF_ACTION;
+}
+function deniedTool(name) {
+    return { title: "Souk tool denied", output: `${name} is exclusive to Kāf Forge agents and cannot be used by this agent.` };
+}
+function parseToolItems(json) {
+    const parsed = JSON.parse(json);
+    const list = Array.isArray(parsed) ? parsed : [parsed];
+    return list.map((item) => RegistryItemSchema.parse(item));
+}
+function parseToolScope(kind, projectPath, context) {
+    if (kind === "global")
+        return { kind: "global" };
+    return { kind: "project", path: projectPath?.trim() || context.worktree };
+}
+function registryHaystack(item) {
+    return [
+        item.name,
+        item.description,
+        item.kind,
+        item.confidence,
+        item.source,
+        item.sourceType,
+        item.repoUrl,
+        item.homepageUrl,
+        item.install?.spec,
+        ...(item.install?.specs ?? []),
+        ...item.tags,
+        ...item.aliases,
+        ...item.alternateKinds,
+        ...item.sources.flatMap((source) => [source.source, source.sourceType, source.name, source.description, source.repoUrl, source.kind, source.confidence]),
+    ].filter(Boolean).join(" ").toLowerCase();
+}
+function installSoukSkillPath(config) {
+    const base = dirname(fileURLToPath(import.meta.url));
+    const skillDir = join(base, "..", "src", "skill");
+    const cfg = config;
+    cfg.skills = cfg.skills ?? {};
+    cfg.skills.paths = Array.from(new Set([...(cfg.skills.paths ?? []), skillDir]));
+}
+function installKafAgents(config) {
+    const loaded = loadSidecarSafe();
+    const sidecar = loaded.config;
+    if (loaded.error)
+        debugLog("Souk config parse failed", `Using defaults for Kāf agents: ${loaded.error}`, true);
+    const model = splitModelRef(sidecar.forge.agent.model);
+    const promptBase = [
+        "You are Kāf, the dedicated OpenCode Souk Forge agent.",
+        `Personality preset: ${sidecar.forge.agent.personality}`,
+        personalityDescription(sidecar.forge.agent.personality),
+        "Always load and use the customize-opencode and souk-installer skills before planning or installing.",
+        "Security analysis is mandatory before any install or config change.",
+        "The souk can make mistakes; be explicit about uncertainty and ask before risky writes.",
+    ].join("\n");
+    const cfg = config;
+    cfg.agent = cfg.agent ?? {};
+    cfg.agent[KAF_PLAN] = {
+        description: "Kāf Forge planning agent for OpenCode Souk installs. Read-only; asks before action mode.",
+        mode: "primary",
+        hidden: true,
+        ...(model ? { model: `${model.providerID}/${model.modelID}` } : {}),
+        ...(sidecar.forge.agent.variant ? { variant: sidecar.forge.agent.variant } : {}),
+        ...(sidecar.forge.agent.temperature !== undefined ? { temperature: sidecar.forge.agent.temperature } : {}),
+        ...(sidecar.forge.agent.top_p !== undefined ? { top_p: sidecar.forge.agent.top_p } : {}),
+        options: sidecar.forge.agent.options ?? {},
+        prompt: [promptBase, "You are in plan mode. Do not edit, write, patch, run install commands, or mutate the system. You may use MCP tools for research, inspection, and appraisal, but not for mutation. Use souk_request_action when ready to ask for action mode."].join("\n\n"),
+        permission: {
+            edit: "deny",
+            bash: "deny",
+            skill: "allow",
+            read: "allow",
+            grep: "allow",
+            glob: "allow",
+            webfetch: "allow",
+            websearch: "allow",
+            [ACTION_TOOL]: "allow",
+            [REGISTRY_SEARCH_TOOL]: "allow",
+            [NATIVE_PREVIEW_TOOL]: "allow",
+            [NATIVE_INSTALL_TOOL]: "deny",
+        },
+    };
+    cfg.agent[KAF_ACTION] = {
+        description: "Kāf Forge action agent for approved OpenCode Souk install plans.",
+        mode: "primary",
+        hidden: true,
+        ...(model ? { model: `${model.providerID}/${model.modelID}` } : {}),
+        ...(sidecar.forge.agent.variant ? { variant: sidecar.forge.agent.variant } : {}),
+        ...(sidecar.forge.agent.temperature !== undefined ? { temperature: sidecar.forge.agent.temperature } : {}),
+        ...(sidecar.forge.agent.top_p !== undefined ? { top_p: sidecar.forge.agent.top_p } : {}),
+        options: sidecar.forge.agent.options ?? {},
+        prompt: [promptBase, "You are in action mode. Execute only the approved Souk Forge plan. Ask before risky writes, network installs, or ambiguous changes."].join("\n\n"),
+        permission: {
+            edit: "ask",
+            bash: "ask",
+            skill: "allow",
+            read: "allow",
+            grep: "allow",
+            glob: "allow",
+            webfetch: "allow",
+            websearch: "allow",
+            [ACTION_TOOL]: "allow",
+            [REGISTRY_SEARCH_TOOL]: "allow",
+            [NATIVE_PREVIEW_TOOL]: "allow",
+            [NATIVE_INSTALL_TOOL]: "ask",
+        },
+    };
+}
+function installToolPermissions(config) {
+    const cfg = config;
+    if (cfg.permission === undefined)
+        cfg.permission = { [ACTION_TOOL]: "deny" };
+    if (cfg.permission && typeof cfg.permission === "object" && !Array.isArray(cfg.permission)) {
+        ;
+        cfg.permission[ACTION_TOOL] = "deny";
+        cfg.permission[REGISTRY_SEARCH_TOOL] = "deny";
+        cfg.permission[NATIVE_PREVIEW_TOOL] = "deny";
+        cfg.permission[NATIVE_INSTALL_TOOL] = "deny";
+    }
+}
+function queueActionContinuation(client, sessionID, plan, risks, actions) {
+    const api = client;
+    const prompt = [
+        "User approved Kāf action mode for this Souk Forge session.",
+        "Execute only the approved plan below. Do not expand scope without asking.",
+        "",
+        "Approved plan:",
+        plan,
+        "",
+        "Security risks acknowledged:",
+        ...risks.map((risk) => `- ${risk}`),
+        "",
+        "Planned actions:",
+        ...actions.map((action) => `- ${action}`),
+    ].join("\n");
+    setTimeout(() => {
+        const payload = { sessionID, agent: KAF_ACTION, parts: [{ type: "text", text: prompt }] };
+        void (api.session?.promptAsync?.(payload) ?? api.session?.prompt?.(payload))?.catch(() => undefined);
+    }, 0);
+}
+export default plugin;

package/dist/install.d.ts

@@ -0,0 +1,18 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { RegistryItem, ScopeChoice, SidecarConfig } from "./config.js";
+export type NativePreview = {
+    supported: boolean;
+    summary: string;
+    warnings: string[];
+};
+export type NativeInstallCallbacks = {
+    confirm?: (title: string, message: string) => Promise<boolean>;
+};
+type InstallSettings = SidecarConfig["install"];
+export declare function previewNativeInstall(items: RegistryItem[], scope: ScopeChoice, settings?: InstallSettings): Promise<NativePreview>;
+export declare function nativeInstall(api: Partial<TuiPluginApi>, items: RegistryItem[], scope: ScopeChoice, callbacks?: NativeInstallCallbacks, settings?: InstallSettings): Promise<{
+    installed: string[];
+    failed: string[];
+}>;
+declare function scopeLabel(scope: ScopeChoice): string;
+export { scopeLabel };