@bradygaster/squad-sdk 0.9.6-insider.2 → 0.10.0

package/dist/marketplace/plugin-state.js

@@ -0,0 +1,278 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, normalize } from 'node:path';
+import { derivePluginRoles, } from './plugin-manifest.js';
+export const PLUGIN_STATE_DIR = 'plugins';
+export const INSTALLED_PLUGINS_FILE = join(PLUGIN_STATE_DIR, 'installed.json');
+export const PLUGIN_LOCK_FILE = join(PLUGIN_STATE_DIR, 'lock.json');
+export const PLUGIN_RUNTIME_FILE = join(PLUGIN_STATE_DIR, 'runtime.json');
+export const PLUGIN_AUDIT_FILE = join(PLUGIN_STATE_DIR, 'audit.jsonl');
+export async function readPluginStates(storage, stateRoot = '') {
+    const [installed, lock, runtime, audit] = await Promise.all([
+        readJsonState(storage, join(stateRoot, INSTALLED_PLUGINS_FILE), { plugins: [] }),
+        readJsonState(storage, join(stateRoot, PLUGIN_LOCK_FILE), { plugins: {} }),
+        readJsonState(storage, join(stateRoot, PLUGIN_RUNTIME_FILE), { plugins: {}, active: {} }),
+        readAuditState(storage, join(stateRoot, PLUGIN_AUDIT_FILE)),
+    ]);
+    runtime.active ??= {};
+    return { installed, lock, runtime, audit };
+}
+export async function buildActivePluginContext(storage, stateRoot = '', options = {}) {
+    const states = await readPluginStates(storage, stateRoot);
+    const maxArtifactChars = options.maxArtifactChars ?? 12_000;
+    const activePluginIds = Array.from(new Set(Object.values(states.runtime.active)
+        .filter((pluginId) => typeof pluginId === 'string')
+        .filter((pluginId) => states.runtime.plugins[pluginId]?.enabled === true))).sort((a, b) => a.localeCompare(b));
+    if (activePluginIds.length === 0) {
+        return '';
+    }
+    const sections = [
+        '## Active Squad Plugins',
+        [
+            'The following enabled Squad plugins contributed declarative static artifacts.',
+            'Squad has not installed upstream packages, started MCP servers, or run external plugin commands.',
+            'Use these artifacts as guidance and metadata when they are relevant to the task.',
+        ].join(' '),
+    ];
+    for (const pluginId of activePluginIds) {
+        const plugin = states.installed.plugins.find((candidate) => candidate.id === pluginId);
+        if (!plugin?.enabled) {
+            continue;
+        }
+        const activeRoles = Object.entries(states.runtime.active)
+            .filter(([, activePluginId]) => activePluginId === plugin.id)
+            .map(([role]) => role)
+            .sort((a, b) => a.localeCompare(b));
+        sections.push([
+            `### ${plugin.name} (${plugin.id}@${plugin.version})`,
+            `Roles: ${activeRoles.length > 0 ? activeRoles.join(', ') : plugin.roles.join(', ')}`,
+            plugin.repository?.url ? `Repository: ${plugin.repository.url}` : undefined,
+            plugin.upstream?.package ? `Upstream package: ${plugin.upstream.package}${plugin.upstream.registry ? ` (${plugin.upstream.registry})` : ''}` : undefined,
+            plugin.mcp?.available ? `MCP metadata: ${plugin.mcp.server ?? plugin.mcp.entryPoint ?? 'available'} (metadata only)` : undefined,
+        ].filter((line) => typeof line === 'string').join('\n'));
+        if (plugin.providers && plugin.providers.length > 0) {
+            sections.push(formatProviderContracts(plugin.providers));
+        }
+        for (const file of [...plugin.files].sort((a, b) => a.target.localeCompare(b.target))) {
+            if (!isSafeInstalledPluginTarget(file.target)) {
+                sections.push(`#### Installed artifact: .squad/${file.target}\nSkipped unsafe plugin state target.`);
+                continue;
+            }
+            const content = await storage.read(join(stateRoot, file.target));
+            if (content === undefined) {
+                sections.push(`#### Installed artifact: .squad/${file.target}\nArtifact listed in plugin state but not found on disk.`);
+                continue;
+            }
+            const trimmed = content.trim();
+            const excerpt = trimmed.length > maxArtifactChars
+                ? `${trimmed.slice(0, maxArtifactChars)}\n\n[truncated: ${trimmed.length - maxArtifactChars} characters omitted]`
+                : trimmed;
+            sections.push(`#### Installed artifact: .squad/${file.target}\n${excerpt}`);
+        }
+    }
+    return sections.join('\n\n');
+}
+export async function writePluginStates(storage, states, stateRoot = '') {
+    await storage.mkdir(join(stateRoot, PLUGIN_STATE_DIR), { recursive: true });
+    await Promise.all([
+        writeJsonState(storage, join(stateRoot, INSTALLED_PLUGINS_FILE), states.installed),
+        writeJsonState(storage, join(stateRoot, PLUGIN_LOCK_FILE), states.lock),
+        writeJsonState(storage, join(stateRoot, PLUGIN_RUNTIME_FILE), states.runtime),
+        writeAuditState(storage, join(stateRoot, PLUGIN_AUDIT_FILE), states.audit),
+    ]);
+}
+export function upsertInstalledPlugin(states, manifest, options) {
+    const now = options.now ?? new Date().toISOString();
+    const existing = states.installed.plugins.find((plugin) => plugin.id === manifest.id);
+    const enabled = existing?.enabled ?? false;
+    const installed = {
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        enabled,
+        source: options.source,
+        installed_at: now,
+        roles: derivePluginRoles(manifest),
+        copilot: manifest.copilot,
+        repository: manifest.repository,
+        upstream: manifest.upstream,
+        mcp: manifest.mcp,
+        providers: manifest.providers,
+        runtime: manifest.runtime,
+        files: options.files,
+    };
+    states.installed.plugins = [
+        ...states.installed.plugins.filter((plugin) => plugin.id !== manifest.id),
+        installed,
+    ].sort((a, b) => a.id.localeCompare(b.id));
+    states.lock.plugins[manifest.id] = {
+        id: manifest.id,
+        version: manifest.version,
+        source: options.source,
+        manifest_sha256: sha256(options.manifestContent),
+        files: options.files,
+        installed_at: now,
+    };
+    states.runtime.plugins[manifest.id] = {
+        enabled,
+        active_version: manifest.version,
+        updated_at: now,
+    };
+    appendAuditEvent(states.audit, {
+        type: 'install',
+        plugin_id: manifest.id,
+        version: manifest.version,
+        timestamp: now,
+        message: `Installed ${manifest.id}@${manifest.version}`,
+    });
+    return installed;
+}
+export function setPluginEnabled(states, pluginId, enabled, now = new Date().toISOString()) {
+    const plugin = states.installed.plugins.find((candidate) => candidate.id === pluginId);
+    if (!plugin) {
+        throw new Error(`Plugin "${pluginId}" is not installed`);
+    }
+    plugin.enabled = enabled;
+    states.runtime.plugins[plugin.id] = {
+        enabled,
+        active_version: plugin.version,
+        updated_at: now,
+    };
+    if (!enabled) {
+        for (const [role, activePluginId] of Object.entries(states.runtime.active)) {
+            if (activePluginId === plugin.id) {
+                delete states.runtime.active[role];
+            }
+        }
+    }
+    else {
+        for (const role of plugin.roles) {
+            const activePluginId = states.runtime.active[role];
+            if (activePluginId && activePluginId !== plugin.id) {
+                throw new Error(`Role "${role}" is already active for plugin "${activePluginId}"`);
+            }
+            states.runtime.active[role] = plugin.id;
+        }
+    }
+    appendAuditEvent(states.audit, {
+        type: enabled ? 'enable' : 'disable',
+        plugin_id: plugin.id,
+        version: plugin.version,
+        timestamp: now,
+        message: `${enabled ? 'Enabled' : 'Disabled'} ${plugin.id}@${plugin.version}`,
+    });
+    return plugin;
+}
+export function switchActivePlugin(states, role, pluginId, now = new Date().toISOString()) {
+    const plugin = states.installed.plugins.find((candidate) => candidate.id === pluginId);
+    if (!plugin) {
+        throw new Error(`Plugin "${pluginId}" is not installed`);
+    }
+    if (!plugin.roles.includes(role)) {
+        throw new Error(`Plugin "${pluginId}" does not declare role "${role}"`);
+    }
+    plugin.enabled = true;
+    states.runtime.active[role] = plugin.id;
+    states.runtime.plugins[plugin.id] = {
+        enabled: true,
+        active_version: plugin.version,
+        updated_at: now,
+    };
+    appendAuditEvent(states.audit, {
+        type: 'switch',
+        plugin_id: plugin.id,
+        version: plugin.version,
+        timestamp: now,
+        message: `Switched ${role} to ${plugin.id}@${plugin.version}`,
+    });
+    return plugin;
+}
+export function removeInstalledPlugin(states, pluginId, now = new Date().toISOString()) {
+    const plugin = states.installed.plugins.find((candidate) => candidate.id === pluginId);
+    if (!plugin) {
+        throw new Error(`Plugin "${pluginId}" is not installed`);
+    }
+    states.installed.plugins = states.installed.plugins.filter((candidate) => candidate.id !== pluginId);
+    delete states.lock.plugins[pluginId];
+    delete states.runtime.plugins[pluginId];
+    for (const [role, activePluginId] of Object.entries(states.runtime.active)) {
+        if (activePluginId === pluginId) {
+            delete states.runtime.active[role];
+        }
+    }
+    appendAuditEvent(states.audit, {
+        type: 'uninstall',
+        plugin_id: plugin.id,
+        version: plugin.version,
+        timestamp: now,
+        message: `Uninstalled ${plugin.id}@${plugin.version}`,
+    });
+    return plugin;
+}
+export function appendAuditEvent(audit, event) {
+    audit.events = [...audit.events, event];
+}
+export function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+async function readJsonState(storage, filePath, fallback) {
+    const content = await storage.read(filePath);
+    if (content === undefined) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not parse ${filePath}: ${message}`);
+    }
+}
+async function writeJsonState(storage, filePath, data) {
+    await storage.write(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+async function readAuditState(storage, filePath) {
+    const content = await storage.read(filePath);
+    if (content === undefined || content.trim() === '') {
+        return { events: [] };
+    }
+    const events = content
+        .split(/\r?\n/)
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+    return { events };
+}
+async function writeAuditState(storage, filePath, audit) {
+    const content = audit.events.map((event) => JSON.stringify(event)).join('\n');
+    await storage.write(filePath, content.length > 0 ? `${content}\n` : '');
+}
+function isSafeInstalledPluginTarget(target) {
+    const normalized = normalize(target).replaceAll('\\', '/');
+    return !isAbsolute(target)
+        && normalized !== '..'
+        && !normalized.startsWith('../')
+        && !normalized.split('/').includes('..');
+}
+function formatProviderContracts(providers) {
+    const lines = [
+        '#### Provider contracts',
+        'Provider contracts are declarative metadata only. Squad does not start MCP servers, call provider tools, or query live provider backends during agent spawn.',
+    ];
+    for (const provider of [...providers].sort((a, b) => a.id.localeCompare(b.id))) {
+        const details = [
+            `type=${provider.type}`,
+            provider.mode ? `mode=${provider.mode}` : undefined,
+            provider.protocol ? `protocol=${provider.protocol}` : undefined,
+            provider.artifact ? `artifact=.squad/${provider.artifact}` : undefined,
+            provider.capabilities && provider.capabilities.length > 0 ? `capabilities=${provider.capabilities.join(', ')}` : undefined,
+            provider.mcp?.server ? `mcp.server=${provider.mcp.server}` : undefined,
+            provider.mcp?.tool ? `mcp.tool=${provider.mcp.tool}` : undefined,
+            provider.mcp?.capability ? `mcp.capability=${provider.mcp.capability}` : undefined,
+        ].filter((detail) => typeof detail === 'string');
+        lines.push(`- ${provider.id}: ${details.join('; ')}`);
+        if (provider.description) {
+            lines.push(`  ${provider.description}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=plugin-state.js.map

package/dist/marketplace/plugin-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-state.js","sourceRoot":"","sources":["../../src/marketplace/plugin-state.ts"],"names":[],"mappings":"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"}

package/dist/memory/index.d.ts

@@ -0,0 +1,262 @@
+import type { StorageProvider } from '../storage/storage-provider.js';
+export type MemoryClass = 'TRANSIENT' | 'LOCAL' | 'DECISION' | 'POLICY' | 'COPILOT_MEMORY' | 'FORBIDDEN';
+export type MemoryLoadGuidance = 'ALWAYS' | 'ON-DEMAND' | 'ARCHIVE' | 'NEVER';
+export interface MemoryGovernanceConfig {
+    version: 1;
+    defaultProvider: 'local' | 'hostInjectedCopilotAdapter' | 'copilot';
+    promptOnlyFallback: true;
+    externalProviders: {
+        hostInjectedCopilotAdapter: {
+            enabled: boolean;
+            requireApproval: boolean;
+        };
+    };
+    policy: {
+        rejectForbidden: true;
+        rejectTransientDurableWrites: true;
+        auditContent: false;
+        auditMaxBytes: number;
+        auditMaxArchives: number;
+    };
+}
+export interface MemoryClassification {
+    class: MemoryClass;
+    allowed: boolean;
+    reason: string;
+    destination: 'none' | 'local' | 'decision-inbox' | 'policy-inbox' | 'external-semantic';
+    loadGuidance: MemoryLoadGuidance;
+}
+export interface MemoryWriteRequest {
+    content: string;
+    title?: string;
+    author?: string;
+    requestedClass?: MemoryClass;
+    approved?: boolean;
+    metadata?: Record<string, string>;
+}
+export interface MemoryWriteResult {
+    stored: boolean;
+    id?: string;
+    classification: MemoryClassification;
+    path?: string;
+}
+export interface MemorySearchResult {
+    id: string;
+    class: MemoryClass;
+    loadGuidance: MemoryLoadGuidance;
+    title: string;
+    path: string;
+    snippet: string;
+    provider?: string;
+    score?: number;
+}
+export interface MemoryAuditRecord {
+    timestamp: string;
+    action: 'classify' | 'write' | 'reject' | 'promote' | 'delete' | 'search' | 'configure' | 'provider-error';
+    id?: string;
+    class?: MemoryClass;
+    title?: string;
+    path?: string;
+    reason?: string;
+    actor?: string;
+    provider?: string;
+}
+export interface CopilotMemoryProviderWriteRequest {
+    content: string;
+    title: string;
+    author?: string;
+    metadata?: Record<string, string>;
+    classification: MemoryClassification;
+}
+export interface CopilotMemoryProviderWriteResult {
+    id: string;
+    path?: string;
+}
+export interface CopilotMemoryProviderSearchResult {
+    id: string;
+    title: string;
+    snippet: string;
+    path?: string;
+}
+export interface MemoryProviderSearchResult extends CopilotMemoryProviderSearchResult {
+    class: MemoryClass;
+    loadGuidance: MemoryLoadGuidance;
+    score?: number;
+}
+export interface CopilotMemoryProviderClient {
+    write(request: CopilotMemoryProviderWriteRequest): Promise<CopilotMemoryProviderWriteResult>;
+    search(query: string): Promise<CopilotMemoryProviderSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+}
+export interface MemoryProviderStatus {
+    id: string;
+    name: string;
+    available: boolean;
+    reason?: string;
+}
+/**
+ * Generic external memory provider contract.
+ *
+ * Implementations receive only pre-classified, non-forbidden, non-transient
+ * memory. The {@link LocalMemoryStore} enforces governance before routing
+ * to any registered provider.
+ */
+export interface MemoryProvider {
+    readonly id: string;
+    readonly name: string;
+    /** Memory classes this provider is designed to store and retrieve. */
+    readonly supportedClasses: ReadonlyArray<MemoryClass>;
+    status(): Promise<MemoryProviderStatus>;
+    write(request: CopilotMemoryProviderWriteRequest): Promise<CopilotMemoryProviderWriteResult>;
+    search(query: string): Promise<MemoryProviderSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+}
+/**
+ * MemPalace — in-memory test double for an external spatial memory provider.
+ *
+ * Models a "memory palace" (method of loci) where memories are stored at
+ * named loci. In production this would be replaced by a real spatial/external
+ * memory service. Set `metadata.locus` on a write request to tag the
+ * destination locus; defaults to `'default'`.
+ *
+ * Accepts: LOCAL, DECISION, POLICY.
+ * Never receives FORBIDDEN, TRANSIENT, or COPILOT_MEMORY (filtered upstream).
+ */
+export declare class MemPalaceMemoryProvider implements MemoryProvider {
+    private readonly maxEntries;
+    readonly id = "mempalace";
+    readonly name = "MemPalace";
+    readonly supportedClasses: ReadonlyArray<MemoryClass>;
+    private readonly loci;
+    constructor(maxEntries?: number);
+    status(): Promise<MemoryProviderStatus>;
+    write(request: CopilotMemoryProviderWriteRequest): Promise<CopilotMemoryProviderWriteResult>;
+    search(query: string): Promise<MemoryProviderSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+    /** Number of stored loci entries — for test introspection only. */
+    get size(): number;
+}
+/**
+ * IndexServer — in-memory test double for a governed knowledge/instruction catalog.
+ *
+ * Models a server-side index of stable instructions and reference knowledge.
+ * In production this would be replaced by a real embedding-search or BM25 index.
+ * Set `metadata.topic` on a write request to tag the catalog entry; defaults to
+ * the memory class (lowercased).
+ *
+ * Accepts: LOCAL, DECISION, POLICY.
+ * Never receives FORBIDDEN, TRANSIENT, or COPILOT_MEMORY (filtered upstream).
+ */
+export declare class IndexServerMemoryProvider implements MemoryProvider {
+    private readonly maxEntries;
+    readonly id = "indexserver";
+    readonly name = "IndexServer";
+    readonly supportedClasses: ReadonlyArray<MemoryClass>;
+    private readonly catalog;
+    constructor(maxEntries?: number);
+    status(): Promise<MemoryProviderStatus>;
+    write(request: CopilotMemoryProviderWriteRequest): Promise<CopilotMemoryProviderWriteResult>;
+    search(query: string): Promise<MemoryProviderSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+    /** Number of catalog entries — for test introspection only. */
+    get size(): number;
+}
+export interface LocalMemoryStoreOptions {
+    rootKind?: 'project' | 'squad';
+    hostInjectedCopilotAdapterClient?: CopilotMemoryProviderClient;
+    /** @deprecated Use hostInjectedCopilotAdapterClient. */
+    copilotMemoryClient?: CopilotMemoryProviderClient;
+    /**
+     * Optional additional external memory providers.
+     * Each provider receives writes/searches for its supported memory classes
+     * AFTER governance classification. FORBIDDEN and TRANSIENT content never
+     * reaches these providers. Results are merged with local search results.
+     */
+    registeredProviders?: MemoryProvider[];
+}
+export declare const REAL_COPILOT_UNAVAILABLE_REASON = "Real Copilot Memory API unavailable: no concrete callable API was found in installed @github/copilot SDK/tooling. Squad will not fake provider=copilot; use hostInjectedCopilotAdapter only when a host supplies a client.";
+export declare class HostInjectedCopilotMemoryAdapter {
+    private readonly client?;
+    constructor(client?: CopilotMemoryProviderClient | undefined);
+    isAvailable(): boolean;
+    write(request: CopilotMemoryProviderWriteRequest): Promise<CopilotMemoryProviderWriteResult>;
+    search(query: string): Promise<CopilotMemoryProviderSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+    private requireClient;
+}
+export declare function ensureMemoryGovernanceDefaults(storage: StorageProvider, projectRoot: string): Promise<string[]>;
+export declare class LocalMemoryStore {
+    private readonly storage;
+    private readonly squadDir;
+    private readonly copilotProvider;
+    private readonly registeredProviders;
+    /**
+     * Async mutex tail for index read-modify-write operations.
+     * Each caller enqueues behind the current tail so concurrent writes
+     * are serialized without OS-level file locking.
+     */
+    private indexLockTail;
+    constructor(storage: StorageProvider, rootDir: string, options?: LocalMemoryStoreOptions);
+    /**
+     * Serialize all index read-modify-write operations.
+     *
+     * All callers that do readIndex() → mutate → writeIndex() must go through
+     * this method so concurrent writes within the same store instance cannot
+     * interleave and lose entries. The critical section is purely async
+     * (no thread blocking), so this is safe in Node.js single-thread land.
+     */
+    private withIndexLock;
+    classify(request: Pick<MemoryWriteRequest, 'content' | 'requestedClass' | 'metadata'>, options?: {
+        audit?: boolean;
+        actor?: string;
+        title?: string;
+    }): Promise<MemoryClassification>;
+    write(request: MemoryWriteRequest): Promise<MemoryWriteResult>;
+    search(query: string): Promise<MemorySearchResult[]>;
+    promote(id: string, targetClass: Exclude<MemoryClass, 'FORBIDDEN' | 'TRANSIENT'>, actor?: string): Promise<MemoryWriteResult>;
+    delete(id: string, actor?: string): Promise<boolean>;
+    providerStatus(): Promise<{
+        defaultProvider: MemoryGovernanceConfig['defaultProvider'];
+        realCopilotMemory: {
+            available: false;
+            configured: boolean;
+            reason: string;
+        };
+        hostInjectedCopilotAdapter: MemoryGovernanceConfig['externalProviders']['hostInjectedCopilotAdapter'] & {
+            clientAvailable: boolean;
+            configured: boolean;
+        };
+        registeredProviders: MemoryProviderStatus[];
+    }>;
+    configureHostInjectedCopilotAdapter(options: {
+        enabled: boolean;
+        requireApproval?: boolean;
+        defaultProvider?: Exclude<MemoryGovernanceConfig['defaultProvider'], 'copilot'>;
+        actor?: string;
+    }): Promise<MemoryGovernanceConfig>;
+    configureCopilotProvider(options: {
+        enabled: boolean;
+        adapter?: 'host' | 'hostInjectedCopilotAdapter';
+        requireApproval?: boolean;
+        defaultProvider?: MemoryGovernanceConfig['defaultProvider'];
+        actor?: string;
+    }): Promise<MemoryGovernanceConfig>;
+    auditLog(): Promise<MemoryAuditRecord[]>;
+    private ensureInitialized;
+    private readConfig;
+    private readIndex;
+    /**
+     * Best-effort backup of a corrupt index file.
+     * Writes the raw content to a `.corrupt` path alongside the index.
+     * Failure to write the backup is suppressed so callers see the original error.
+     */
+    private backupCorruptIndex;
+    private writeIndex;
+    private audit;
+    private rotateAuditIfNeeded;
+    private destinationPath;
+    private renderMemoryFile;
+    private absoluteFromEntryPath;
+    private updateMemoryFileMetadata;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"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"}