@sayknow-cli/coding-agent 0.3.0 → 0.3.2

package/bin/skc.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "@sayknow-cli/coding-agent/cli";
+
+await runCli(process.argv.slice(2));

package/dist/types/cli/mcp-cli.d.ts

@@ -0,0 +1,25 @@
+import type { MCPServerConfig } from "../runtime-mcp/types";
+export type MCPAction = "add" | "list" | "remove";
+export interface MCPCommandArgs {
+    action: MCPAction;
+    name?: string;
+    commandArgs?: string[];
+    flags: {
+        project?: boolean;
+        force?: boolean;
+        json?: boolean;
+        type?: "stdio" | "http" | "sse";
+        command?: string;
+        url?: string;
+        arg?: string[];
+        env?: string[];
+        header?: string[];
+        cwd?: string;
+        timeout?: number;
+    };
+    cwd?: string;
+}
+export declare class MCPArgsError extends Error {
+}
+export declare function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig;
+export declare function runMCPCommand(args: MCPCommandArgs): Promise<void>;

package/dist/types/cli/notify-cli.d.ts

@@ -17,6 +17,8 @@ export interface NotifyCommandDeps {
     pollIntervalMs?: number;
     setupChatId?: string;
     setupRedact?: boolean;
+    setupInteractive?: boolean;
+    threadedModePrompt?: (message: string) => Promise<string>;
 }
 export declare function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined;
 export declare function runNotifyCommand(cmd: NotifyCommandArgs, deps?: NotifyCommandDeps): Promise<void>;

package/dist/types/cli/plugin-cli.d.ts

@@ -17,6 +17,8 @@ export interface PluginCommandArgs {
         disable?: string;
         set?: string;
         scope?: "user" | "project";
+        user?: boolean;
+        project?: boolean;
     };
 }
 /**

package/dist/types/cli.d.ts

@@ -1,3 +1,9 @@
 #!/usr/bin/env bun
+/**
+ * CLI entry point — registers all commands explicitly and delegates to the
+ * lightweight CLI runner from pi-utils.
+ */
+import { type CommandEntry } from "@sayknow-cli/utils/cli";
+export declare const commands: CommandEntry[];
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/types/commands/mcp.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Direct MCP server registration for standalone SKC.
+ */
+import { Command } from "@sayknow-cli/utils/cli";
+import { type MCPAction } from "../cli/mcp-cli";
+export default class MCP extends Command {
+    static description: string;
+    static delegateHelp: boolean;
+    static examples: string[];
+    static args: {
+        action: import("@sayknow-cli/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            options: MCPAction[];
+        };
+        name: import("@sayknow-cli/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+        };
+        commandArgs: import("@sayknow-cli/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            multiple: true;
+        };
+    };
+    static flags: {
+        project: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        force: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        json: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+        type: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            options: string[];
+        };
+        command: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        url: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        arg: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        env: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        header: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        cwd: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        timeout: import("@sayknow-cli/utils/cli").FlagDescriptor<"integer"> & {
+            description: string;
+        };
+    };
+    run(): Promise<void>;
+    private printHelp;
+}

package/dist/types/commands/plugin.d.ts

@@ -47,6 +47,12 @@ export default class Plugin extends Command {
             description: string;
             options: string[];
         };
+        user: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        project: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
     };
     run(): Promise<void>;
 }

package/dist/types/commands/session.d.ts

@@ -18,6 +18,12 @@ export default class Session extends Command {
             description: string;
             default: boolean;
         };
+        "session-id": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "state-file": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
     };
     static examples: string[];
     run(): Promise<void>;

package/dist/types/config/keybindings.d.ts

@@ -230,8 +230,8 @@ export declare const KEYBINDINGS: {
         readonly description: "Open external editor";
     };
     readonly "app.message.followUp": {
-        readonly defaultKeys: "ctrl+enter";
-        readonly description: "Send follow-up message";
+        readonly defaultKeys: [];
+        readonly description: "Send follow-up message (no default; Ctrl+Enter inserts a newline)";
     };
     readonly "app.message.queue": {
         readonly defaultKeys: "alt+enter";

package/dist/types/config/model-profile-activation.d.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@sayknow-cli/agent-core";
 import type { Api, Model } from "@sayknow-cli/ai";
 import type { AgentSession } from "../session/agent-session";
-import { type ModelRegistry } from "./model-registry";
+import { type ModelRegistry, type SkcModelAssignmentTargetId } from "./model-registry";
 import type { Settings } from "./settings";
 type ModelProfileActivationSession = Pick<AgentSession, "model" | "thinkingLevel" | "sessionId"> & {
     setModelTemporary?: AgentSession["setModelTemporary"];
@@ -40,6 +40,13 @@ export interface PreparedModelProfileActivation {
      */
     previousSessionDefaultModel: string | undefined;
 }
+export interface MaterializeModelProfileAssignmentOptions {
+    session: Pick<ModelProfileActivationSession, "model" | "thinkingLevel" | "setActiveModelProfile" | "getActiveModelProfile">;
+    settings: Pick<Settings, "clearOverride" | "get" | "override" | "set">;
+    role: SkcModelAssignmentTargetId;
+    selector: string;
+}
+export declare function materializeActiveModelProfileAssignment(options: MaterializeModelProfileAssignmentOptions): boolean;
 export declare function formatModelProfileCredentialError(profileName: string, providers: readonly string[]): string;
 export declare function prepareModelProfileActivation(options: PrepareModelProfileActivationOptions): Promise<PreparedModelProfileActivation>;
 export declare function applyPreparedModelProfileActivation(prepared: PreparedModelProfileActivation, options?: {

package/dist/types/config/settings-schema.d.ts

@@ -130,6 +130,22 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "string";
         readonly default: undefined;
     };
+    readonly "notifications.discord.botToken": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.discord.channelId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.slack.botToken": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.slack.channelId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
     readonly "notifications.redact": {
         readonly type: "boolean";
         readonly default: false;
@@ -2512,6 +2528,15 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Allow the read tool to fetch and process URLs";
         };
     };
+    readonly "web.insaneFallback": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly ui: {
+            readonly tab: "tools";
+            readonly label: "Insane Search Fallback";
+            readonly description: "Opt in to the vendored insane-search escalation for blocked public URL reads (403/WAF/JS-gated). Off by default. Requires preinstalled python3 + curl_cffi (and node + playwright/stealth for the browser phase); changes network posture by enabling TLS/browser impersonation for public pages.";
+        };
+    };
     readonly "github.enabled": {
         readonly type: "boolean";
         readonly default: false;
@@ -2561,7 +2586,7 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "array";
         readonly default: string[];
         readonly items: {
-            readonly enum: readonly ["duckduckgo", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
+            readonly enum: readonly ["duckduckgo", "insane", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
         };
         readonly ui: {
             readonly tab: "tools";
@@ -3164,7 +3189,7 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "providers.webSearch": {
         readonly type: "enum";
-        readonly values: readonly ["auto", "duckduckgo", "exa", "brave", "jina", "kimi", "zai", "perplexity", "anthropic", "gemini", "codex", "xai", "tavily", "kagi", "synthetic", "parallel", "searxng"];
+        readonly values: readonly ["auto", "duckduckgo", "insane", "exa", "brave", "jina", "kimi", "zai", "perplexity", "anthropic", "gemini", "codex", "xai", "tavily", "kagi", "synthetic", "parallel", "searxng"];
         readonly default: "auto";
         readonly ui: {
             readonly tab: "providers";
@@ -3178,6 +3203,10 @@ export declare const SETTINGS_SCHEMA: {
                 readonly value: "duckduckgo";
                 readonly label: "DuckDuckGo";
                 readonly description: "Keyless default \u2014 no API key or OAuth required";
+            }, {
+                readonly value: "insane";
+                readonly label: "Insane";
+                readonly description: "Keyless safe public-route fallback inspired by upstream insane-search";
             }, {
                 readonly value: "exa";
                 readonly label: "Exa";
@@ -3650,6 +3679,14 @@ export interface NotificationsSettings {
         botToken: string | undefined;
         chatId: string | undefined;
     };
+    discord: {
+        botToken: string | undefined;
+        channelId: string | undefined;
+    };
+    slack: {
+        botToken: string | undefined;
+        channelId: string | undefined;
+    };
     redact: boolean;
     daemon: {
         idleTimeoutMs: number;

package/dist/types/deep-interview/plaintext-gate-guard.d.ts

@@ -0,0 +1,11 @@
+export type DeepInterviewPlaintextAskLeakOption = "Yes, crystallize" | "Adjust wording" | "Missing scope";
+export type DeepInterviewPlaintextAskLeakResult = {
+    kind: "deep_interview_plaintext_ask_leak";
+    matchedOptions: DeepInterviewPlaintextAskLeakOption[];
+    signals: {
+        optionsHeading: true;
+        restateIntent: true;
+        deepInterviewContext: boolean;
+    };
+};
+export declare function detectDeepInterviewPlaintextAskLeak(text: string): DeepInterviewPlaintextAskLeakResult | null;

package/dist/types/defaults/skc-defaults.d.ts

@@ -1,6 +1,6 @@
 export declare const DEFAULT_SKC_DEFINITION_NAMES: readonly ["deep-interview", "ralplan", "team", "ultragoal"];
 export type DefaultSkcDefinitionName = (typeof DEFAULT_SKC_DEFINITION_NAMES)[number];
-export type DefaultSkcDefinitionKind = "skill" | "skill-fragment" | "rule";
+export type DefaultSkcDefinitionKind = "skill" | "skill-fragment";
 export type EmbeddedDefaultSkcSkill = {
     name: DefaultSkcDefinitionName;
     description: string;
@@ -23,13 +23,7 @@ export interface DefaultSkcSkillFragmentDefinition {
     relativePath: string;
     content: string;
 }
-export interface DefaultSkcRuleDefinition {
-    kind: "rule";
-    name: string;
-    relativePath: string;
-    content: string;
-}
-export type DefaultSkcDefinition = DefaultSkcSkillDefinition | DefaultSkcSkillFragmentDefinition | DefaultSkcRuleDefinition;
+export type DefaultSkcDefinition = DefaultSkcSkillDefinition | DefaultSkcSkillFragmentDefinition;
 export interface InstallDefaultSkcDefinitionsOptions {
     check?: boolean;
     force?: boolean;
@@ -45,11 +39,6 @@ export type DefaultSkcDefinitionInstallFile = {
     parentSkillName: DefaultSkcDefinitionName;
     path: string;
     status: DefaultSkcInstallStatus;
-} | {
-    kind: "rule";
-    name: string;
-    path: string;
-    status: DefaultSkcInstallStatus;
 };
 export interface DefaultSkcDefinitionInstallResult {
     targetRoot: string;

package/dist/types/extensibility/shared-events.d.ts

@@ -172,6 +172,7 @@ export interface AutoCompactionEndEvent {
     errorMessage?: string;
     /** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
     skipped?: boolean;
+    continuationSkipReason?: "auto_continue_disabled_non_resumable_tail";
 }
 /** Fired when auto-retry starts */
 export interface AutoRetryStartEvent {

package/dist/types/extensibility/skc-plugins/compiler.d.ts

@@ -0,0 +1,19 @@
+import { type NormalizedSkcPluginBundle } from "./types";
+/**
+ * Stable surface extension-id builders. Kept here so install, runtime, and
+ * observability all derive identical ids.
+ */
+export declare const surfaceIds: {
+    readonly tool: (name: string) => string;
+    readonly hook: (event: string, phase: string | undefined, target: string | undefined, name: string) => string;
+    readonly mcp: (name: string) => string;
+    readonly systemAppendix: (plugin: string, name: string) => string;
+    readonly agentAppendix: (agent: string, plugin: string, name: string) => string;
+    readonly subskill: (parent: string, phase: string, activationArg: string) => string;
+};
+/**
+ * Pure compile step: reads only the manifest, subskill frontmatter, and
+ * declared files (as bytes for hashing/existence). It NEVER imports or executes
+ * plugin tool/hook code.
+ */
+export declare function compileSkcPluginBundle(root: string): Promise<NormalizedSkcPluginBundle>;

package/dist/types/extensibility/skc-plugins/constrained-hooks.d.ts

@@ -0,0 +1,29 @@
+import { type SessionQuarantine } from "./session-validation";
+/**
+ * Constrained plugin-hook loader.
+ *
+ * Third-party plugin hooks are NOT given the broad first-party HookAPI. They
+ * receive a restricted API that can only register a handler for their declared
+ * event; every session-mutation / command / shell capability throws
+ * security_policy. After the factory runs we verify it registered exactly the
+ * declared event (and nothing else), or the hook is quarantined.
+ */
+export interface ConstrainedPluginHook {
+    plugin: string;
+    event: string;
+    target?: string;
+    phase?: "before" | "after";
+    handler: (...args: any[]) => unknown;
+}
+export interface ConstrainedHookLoadResult {
+    hooks: ConstrainedPluginHook[];
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Load all always-on constrained plugin hooks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns empty when
+ * no plugins are installed.
+ */
+export declare function loadConstrainedPluginHooks(input: {
+    cwd: string;
+}): Promise<ConstrainedHookLoadResult>;

package/dist/types/extensibility/skc-plugins/index.d.ts

@@ -1,8 +1,17 @@
 export * from "./activation";
+export * from "./compiler";
+export * from "./constrained-hooks";
 export * from "./injection";
+export * from "./installer";
 export * from "./loader";
+export * from "./mcp-policy";
+export * from "./observability";
 export * from "./paths";
+export * from "./prompt-appendix";
+export * from "./registry";
+export * from "./runtime-adapters";
 export * from "./schema";
+export * from "./session-validation";
 export * from "./state";
 export * from "./tools";
 export * from "./types";

package/dist/types/extensibility/skc-plugins/injection.d.ts

@@ -29,3 +29,12 @@ export declare function buildAgentSubskillInjection(input: {
     sessionId?: string;
     agentName: string;
 }): Promise<string>;
+import type { SkcPluginRegistryEntry } from "./types";
+/**
+ * Tier-1 advertisement for a workflow parent skill: bounded, metadata-only list
+ * of installed sub-skills bound to `parent`, rendered ONLY in that parent's
+ * prompt (never the global public-workflow-surface). No body content.
+ */
+export declare function buildSubskillAdvertisement(entries: readonly SkcPluginRegistryEntry[], parent: string, phase?: string): string;
+/** Tier-1 advertisement for a role-agent parent. */
+export declare function buildAgentSubskillAdvertisement(entries: readonly SkcPluginRegistryEntry[], agentName: string): string;

package/dist/types/extensibility/skc-plugins/installer.d.ts

@@ -0,0 +1,13 @@
+import { type SkcPluginRegistryEntry, type SkcPluginScope } from "./types";
+export interface InstallSkcPluginOptions {
+    scope: SkcPluginScope;
+    cwd: string;
+    force?: boolean;
+}
+export interface InstallSkcPluginResult {
+    status: "installed" | "updated" | "unchanged";
+    entry: SkcPluginRegistryEntry;
+}
+export declare function installSkcPluginBundle(source: string, options: InstallSkcPluginOptions): Promise<InstallSkcPluginResult>;
+/** True only when the source actually resolves to a SKC plugin bundle (root sayknow-plugin.json). */
+export declare function isSkcPluginBundleSource(source: string): Promise<boolean>;

package/dist/types/extensibility/skc-plugins/mcp-policy.d.ts

@@ -0,0 +1,26 @@
+import { type SkcPluginMcpManifestEntry } from "./types";
+export declare function isDeniedIpv4(host: string): boolean;
+export declare function isDeniedIpv6(host: string): boolean;
+/**
+ * Synchronous URL policy (scheme, credentials, host literal ranges). Used for
+ * the primary endpoint and any redirect/token/discovery URL.
+ */
+export declare function assertUrlAllowed(rawUrl: string, label?: string): URL;
+/** Reject headers with control characters / CRLF injection. */
+export declare function assertHeadersAllowed(headers: Record<string, string> | undefined): void;
+/**
+ * Runtime DNS check: resolve the host and ensure no resolved address falls in a
+ * denied range (covers DNS rebinding when re-run before each connect).
+ */
+export declare function assertDnsResolvesPublic(hostname: string, label?: string): Promise<void>;
+export interface StdioPolicyContext {
+    pluginRoot: string;
+}
+/** stdio launcher/path confinement policy. */
+export declare function assertStdioAllowed(entry: SkcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;
+/**
+ * Install-time MCP policy (no network required). Validates scheme/host literals
+ * and stdio confinement. Runtime connect additionally calls
+ * assertDnsResolvesPublic and re-validates redirect/token URLs.
+ */
+export declare function assertMcpInstallPolicy(entry: SkcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;

package/dist/types/extensibility/skc-plugins/observability.d.ts

@@ -0,0 +1,27 @@
+import type { SkcPluginRegistryEntry, SkcPluginScope } from "./types";
+/**
+ * Observability for SKC plugin bundle surfaces, consumable by the extension
+ * dashboard / state manager. Each surface row carries its stable extension id,
+ * owning plugin, scope, source kind, enabled/disabled/quarantined status, and a
+ * content hash. MCP auth/header values are NEVER included.
+ */
+export type PluginSurfaceStatus = "enabled" | "disabled" | "quarantined";
+export interface PluginSurfaceRow {
+    extensionId: string;
+    kind: "tool" | "hook" | "mcp" | "system-appendix" | "agent-appendix" | "subskill";
+    plugin: string;
+    scope: SkcPluginScope;
+    sourceKind: SkcPluginRegistryEntry["source"]["kind"];
+    status: PluginSurfaceStatus;
+    hash: string;
+    quarantineCode?: string;
+}
+export interface PluginObservabilitySummary {
+    plugins: number;
+    surfaces: PluginSurfaceRow[];
+}
+/**
+ * Build the observability summary for the effective registry at `cwd`, including
+ * hash-drift and session-collision quarantine status.
+ */
+export declare function summarizeSkcPluginObservability(cwd: string): Promise<PluginObservabilitySummary>;

package/dist/types/extensibility/skc-plugins/prompt-appendix.d.ts

@@ -0,0 +1,16 @@
+import type { SkcPluginRegistryEntry, SkcSubskillParentAgent } from "./types";
+export interface RenderedPluginAppendices {
+    /** Combined system-appendix block text (empty if none). */
+    system: string;
+    /** Per-agent appendix block text. */
+    byAgent: Map<SkcSubskillParentAgent, string>;
+    /** Stable digest of all rendered appendix content + identities (for cache/refresh). */
+    digest: string;
+}
+/**
+ * Build appendix blocks from the active, enabled registry entries in their
+ * deterministic order. Per-appendix and total size caps are enforced
+ * fail-closed (oversize content is dropped with a marker, never silently
+ * truncated into the prompt as authoritative text).
+ */
+export declare function renderPluginAppendices(entries: readonly SkcPluginRegistryEntry[]): Promise<RenderedPluginAppendices>;

package/dist/types/extensibility/skc-plugins/registry.d.ts

@@ -0,0 +1,32 @@
+import { type SkcPluginRegistry, type SkcPluginRegistryEntry, type SkcPluginScope } from "./types";
+export declare function registryRootForScope(scope: SkcPluginScope, cwd: string): string;
+export declare function registryPathForScope(scope: SkcPluginScope, cwd: string): string;
+/**
+ * Deterministic ordering: scope (user before project) -> normalized name ->
+ * resolved plugin root. Collisions are errors elsewhere; order only controls
+ * stable hook/appendix sequencing.
+ */
+export declare function sortRegistryEntries(entries: SkcPluginRegistryEntry[]): SkcPluginRegistryEntry[];
+export declare function readRegistry(scope: SkcPluginScope, cwd: string): Promise<SkcPluginRegistry>;
+export declare function withRegistryLock<T>(scope: SkcPluginScope, cwd: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Lock-free atomic write (temp+fsync+rename). Only call while already holding
+ * the per-scope registry lock via withRegistryLock.
+ */
+export declare function writeRegistryUnlocked(registry: SkcPluginRegistry, cwd: string): Promise<void>;
+/**
+ * Atomic registry write: write to a temp sibling, fsync, then rename. Guarded
+ * by an interprocess lockfile so concurrent installs cannot clobber each other.
+ */
+export declare function writeRegistry(registry: SkcPluginRegistry, cwd: string): Promise<void>;
+/**
+ * Mutate a scope's registry as a single locked read-modify-write transaction so
+ * concurrent installs cannot lose each other's updates. The mutator receives a
+ * sorted copy and returns the next entry list.
+ */
+export declare function updateRegistry(scope: SkcPluginScope, cwd: string, mutator: (entries: SkcPluginRegistryEntry[]) => SkcPluginRegistryEntry[]): Promise<SkcPluginRegistry>;
+/**
+ * Effective registry for a cwd: user + project entries in deterministic order.
+ */
+export declare function loadEffectiveSkcPluginRegistry(cwd: string): Promise<SkcPluginRegistryEntry[]>;
+export declare function registryEntryFingerprint(entry: SkcPluginRegistryEntry): string;

package/dist/types/extensibility/skc-plugins/runtime-adapters.d.ts

@@ -0,0 +1,64 @@
+import type { CustomTool } from "../custom-tools/types";
+import { type SessionQuarantine } from "./session-validation";
+export interface AlwaysOnPluginTools {
+    tools: CustomTool[];
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Load the always-on plugin tool surfaces for the effective registry at `cwd`.
+ *
+ * Safety properties:
+ * - Hash drift quarantines the plugin (runtime_mismatch) before any import.
+ * - Session-start collisions vs reserved/built-in names quarantine fail-closed.
+ * - Manifest-declared tool names are authoritative: a factory that returns a
+ *   different/extra/missing name is rejected with runtime_mismatch and skipped.
+ * - Reserved tool names are never overwritten.
+ *
+ * Returns an empty result when no plugins are installed, so callers that always
+ * call this in `createAgentSession` incur no behavior change without plugins.
+ */
+export declare function loadAlwaysOnPluginTools(input: {
+    cwd: string;
+    reservedToolNames: string[];
+}): Promise<AlwaysOnPluginTools>;
+/**
+ * Render the always-on system-appendix blocks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns "" when no
+ * plugins are installed/enabled. Safe to call unconditionally at session start.
+ */
+export declare function renderAlwaysOnSystemAppendices(input: {
+    cwd: string;
+}): Promise<string>;
+/**
+ * Render the agent-appendix block and Tier-1 sub-skill advertisement for a role
+ * agent at session/spawn time. Hash-drift + collision quarantine applied first.
+ * Returns empty strings when nothing applies.
+ */
+export declare function renderAgentPromptAdditions(input: {
+    cwd: string;
+    agentName: string;
+}): Promise<{
+    appendix: string;
+    advertisement: string;
+}>;
+/**
+ * Render the Tier-1 sub-skill advertisement for a workflow parent skill.
+ * Returns "" when nothing applies. Quarantine applied first.
+ */
+export declare function renderSkillAdvertisement(input: {
+    cwd: string;
+    skillName: string;
+    phase?: string;
+}): Promise<string>;
+/**
+ * Convert active plugin-bundle MCP surfaces into runtime MCPServerConfig entries,
+ * applying install + runtime MCP policy (URL scheme/private-range deny, DNS
+ * re-resolution for http/sse, stdio root-confinement) before connection. Servers
+ * failing policy are quarantined and excluded. Returns {} when none.
+ */
+export declare function buildPluginMcpConfigs(input: {
+    cwd: string;
+}): Promise<{
+    configs: Record<string, any>;
+    quarantine: SessionQuarantine[];
+}>;

package/dist/types/extensibility/skc-plugins/session-validation.d.ts

@@ -0,0 +1,42 @@
+import type { SkcPluginLoadErrorCode, SkcPluginRegistryEntry } from "./types";
+/**
+ * Session-start validation: the registry is the collision authority. Capability
+ * provider output is supplied as EVIDENCE only; plugin surfaces are never
+ * resolved by capability first-wins. Offending surfaces are quarantined
+ * fail-closed with a stable error code rather than silently shadowed.
+ */
+export interface SessionCapabilityEvidence {
+    /** Built-in + provider tool names already present before plugin insertion. */
+    toolNames?: Iterable<string>;
+    /** Non-plugin MCP server names from providers/built-ins. */
+    mcpNames?: Iterable<string>;
+    /** Non-plugin hook keys (event:phase:target:name) from providers/built-ins. */
+    hookKeys?: Iterable<string>;
+    /** Existing appendix extension ids already present. */
+    appendixIds?: Iterable<string>;
+}
+export interface SessionQuarantine {
+    plugin: string;
+    surfaceId: string;
+    code: SkcPluginLoadErrorCode;
+    message: string;
+}
+export interface SessionValidationResult {
+    /** Registry entries (enabled, non-quarantined) whose surfaces may activate. */
+    active: SkcPluginRegistryEntry[];
+    /** Per-surface quarantine records (fail-closed). */
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Re-verify that the installed files still match the registry's recorded hashes.
+ * Drift (manual edits, partial writes) quarantines the whole plugin with
+ * runtime_mismatch.
+ */
+export declare function verifyEntryHashes(entry: SkcPluginRegistryEntry): Promise<SessionQuarantine | null>;
+/**
+ * Validate the effective installed registry against the current capability
+ * universe (evidence) and across plugins. Returns the entries that may activate
+ * plus per-surface quarantine records. Disabled entries/surfaces are skipped
+ * (not an error).
+ */
+export declare function validateSessionBundles(entries: readonly SkcPluginRegistryEntry[], evidence?: SessionCapabilityEvidence, preQuarantined?: readonly SessionQuarantine[]): SessionValidationResult;