aptly 0.1.0

package/dist/src/report.d.ts

@@ -0,0 +1,51 @@
+declare const statuses: readonly ['ok', 'warning', 'error', 'unknown'];
+export type DiagnosticStatus = typeof statuses[number];
+declare const checkCodes: Readonly<{
+    node_runtime: string[];
+    classification_provider: string[];
+    api_key: string[];
+    ledger_location: string[];
+    operator_configuration: string[];
+    host_evidence: string[];
+    host_cli_versions: string[];
+}>;
+declare const privacyKeys: readonly ['task_text', 'paths', 'environment_values', 'credentials', 'raw_errors'];
+export type DiagnosticCheckId = keyof typeof checkCodes;
+export interface DiagnosticCheck {
+    id: DiagnosticCheckId;
+    status: DiagnosticStatus;
+    code: string;
+}
+export type DiagnosticSummary = Record<DiagnosticStatus, number>;
+export interface Diagnostic {
+    schema_version: 1;
+    report_id: string;
+    generated_at: string;
+    tool: {
+        name: 'aptly' | 'subagent-decisions';
+        version: string;
+    };
+    environment: {
+        node: string;
+        platform: string;
+        arch: string;
+    };
+    checks: DiagnosticCheck[];
+    summary: DiagnosticSummary;
+    privacy: Record<typeof privacyKeys[number], false>;
+    network_requests: 0;
+    paid_calls: 0;
+}
+export interface ReportExportResult {
+    report_id: string;
+    files: string[];
+    summary: DiagnosticSummary;
+}
+export declare function renderDiagnosticMarkdown(diagnostic: unknown): string;
+/** Write reviewed, local attachments only. No network, process execution, or config changes. */
+export declare function exportDiagnosticReport({ diagnostic, format, outputDir }?: {
+    diagnostic?: unknown;
+    format?: unknown;
+    outputDir?: unknown;
+}): ReportExportResult;
+export {};

package/dist/src/report.js

@@ -0,0 +1,177 @@
+import { closeSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, rmdirSync, unlinkSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { assertNoRedirectedAncestors } from './files.js';
+import { errorCode } from './types.js';
+const statuses = ['ok', 'warning', 'error', 'unknown'];
+const checkCodes = Object.freeze({
+    node_runtime: ['node_supported', 'node_unsupported'],
+    classification_provider: ['provider_fixture', 'provider_decisions', 'provider_invalid'],
+    api_key: ['key_present_unverified', 'key_missing', 'key_not_required'],
+    ledger_location: ['ledger_private_location_ready', 'ledger_not_configured', 'ledger_location_unavailable'],
+    operator_configuration: ['configuration_default_shadow', 'configuration_valid', 'configuration_unavailable', 'configuration_invalid'],
+    host_evidence: ['host_evidence_not_configured', 'host_evidence_loaded_unverified', 'host_evidence_unavailable', 'host_evidence_changed'],
+    host_cli_versions: ['host_cli_not_probed'],
+});
+const privacyKeys = ['task_text', 'paths', 'environment_values', 'credentials', 'raw_errors'];
+const platforms = ['aix', 'android', 'darwin', 'freebsd', 'haiku', 'linux', 'netbsd', 'openbsd', 'sunos', 'win32', 'unknown'];
+const architectures = ['arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc', 'ppc64', 'riscv64', 's390', 's390x', 'x64', 'unknown'];
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+const semver = /^(?:0|[1-9]\d{0,5})\.(?:0|[1-9]\d{0,5})\.(?:0|[1-9]\d{0,5})(?:-[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?(?:\+[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?$/;
+const own = (obj, key) => Object.hasOwn(obj, key);
+const fail = (code) => Object.assign(new Error(code), { code });
+function exact(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        return false;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return Object.keys(descriptors).length === keys.length && keys.every(key => own(descriptors, key) && own(descriptors[key], 'value') && descriptors[key].enumerable) &&
+        Object.getOwnPropertySymbols(value).length === 0;
+}
+function version(value) { return typeof value === 'string' && value.length <= 64 && semver.test(value) && !/sk-/i.test(value); }
+const isStatus = (value) => typeof value === 'string' && statuses.includes(value);
+const isCheckId = (value) => typeof value === 'string' && own(checkCodes, value);
+function validateDiagnostic(value) {
+    try {
+        if (!exact(value, ['schema_version', 'report_id', 'generated_at', 'tool', 'environment', 'checks', 'summary', 'privacy', 'network_requests', 'paid_calls']) ||
+            value.schema_version !== 1 || typeof value.report_id !== 'string' || !uuid.test(value.report_id) ||
+            typeof value.generated_at !== 'string' || value.generated_at.length !== 24 ||
+            !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value.generated_at) ||
+            !Number.isFinite(Date.parse(value.generated_at)) || new Date(value.generated_at).toISOString() !== value.generated_at ||
+            !exact(value.tool, ['name', 'version']) || typeof value.tool.name !== 'string' || !['aptly', 'subagent-decisions'].includes(value.tool.name) || !version(value.tool.version) ||
+            !exact(value.environment, ['node', 'platform', 'arch']) || !version(value.environment.node) ||
+            typeof value.environment.platform !== 'string' || !platforms.includes(value.environment.platform) ||
+            typeof value.environment.arch !== 'string' || !architectures.includes(value.environment.arch) ||
+            !Array.isArray(value.checks) || value.checks.length !== Object.keys(checkCodes).length ||
+            !exact(value.summary, statuses) || !exact(value.privacy, privacyKeys) || value.network_requests !== 0 || value.paid_calls !== 0)
+            throw fail('report_invalid_diagnostic');
+        const privacy = value.privacy, summary = value.summary;
+        if (privacyKeys.some(key => privacy[key] !== false))
+            throw fail('report_invalid_diagnostic');
+        const seen = new Set(), counts = { ok: 0, warning: 0, error: 0, unknown: 0 };
+        const checks = value.checks.map((check) => {
+            if (!exact(check, ['id', 'status', 'code']) || !isCheckId(check.id) || seen.has(check.id) ||
+                !isStatus(check.status) || typeof check.code !== 'string' || !checkCodes[check.id].includes(check.code))
+                throw fail('report_invalid_diagnostic');
+            seen.add(check.id);
+            counts[check.status]++;
+            return { id: check.id, status: check.status, code: check.code };
+        });
+        if (statuses.some(key => summary[key] !== counts[key]))
+            throw fail('report_invalid_diagnostic');
+        return { schema_version: 1, report_id: value.report_id.toLowerCase(), generated_at: value.generated_at,
+            tool: { name: value.tool.name, version: value.tool.version },
+            environment: { node: value.environment.node, platform: value.environment.platform, arch: value.environment.arch },
+            checks, summary: counts, privacy: { task_text: false, paths: false, environment_values: false, credentials: false, raw_errors: false }, network_requests: 0, paid_calls: 0 };
+    }
+    catch {
+        throw fail('report_invalid_diagnostic');
+    }
+}
+export function renderDiagnosticMarkdown(diagnostic) {
+    const value = validateDiagnostic(diagnostic);
+    return [
+        '# Diagnostic report', '',
+        `Report ID: \`${value.report_id}\``, `Schema version: ${value.schema_version}`, `Generated at: ${value.generated_at}`, '',
+        '| Environment | Value |', '| --- | --- |',
+        `| Tool | ${value.tool.name} |`, `| Tool version | ${value.tool.version} |`,
+        `| Node.js | ${value.environment.node} |`, `| Platform | ${value.environment.platform} |`, `| Architecture | ${value.environment.arch} |`, '',
+        '| Check | Status | Code |', '| --- | --- | --- |',
+        ...value.checks.map(check => `| ${check.id} | ${check.status} | ${check.code} |`), '',
+        `Summary: ok=${value.summary.ok}, warning=${value.summary.warning}, error=${value.summary.error}, unknown=${value.summary.unknown}.`,
+        'Network requests: 0. Paid calls: 0.', '',
+        'This attachment contains only allowlisted diagnostic fields. It contains no task text, private paths, environment values, credentials, or raw errors.',
+        'Key presence does not prove authentication. Host CLI versions were not probed. Review this file before attaching it to an issue; nothing is uploaded automatically.', '',
+    ].join('\n');
+}
+function privateDirectory(path, created) {
+    const missing = [];
+    let existing = path;
+    while (true) {
+        try {
+            lstatSync(existing);
+            break;
+        }
+        catch (error) {
+            if (errorCode(error) !== 'ENOENT')
+                throw error;
+            missing.push(existing);
+            const parent = dirname(existing);
+            if (parent === existing)
+                throw fail('report_output_unavailable');
+            existing = parent;
+        }
+    }
+    assertNoRedirectedAncestors(existing);
+    for (const dir of missing.reverse()) {
+        assertNoRedirectedAncestors(dirname(dir));
+        try {
+            mkdirSync(dir, { mode: 0o700 });
+            created.push(dir);
+            chmodSync(dir, 0o700);
+        }
+        catch (error) {
+            if (errorCode(error) !== 'EEXIST')
+                throw error;
+        }
+        assertNoRedirectedAncestors(dir);
+        if (!lstatSync(dir).isDirectory())
+            throw fail('report_output_unavailable');
+    }
+    assertNoRedirectedAncestors(path);
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) ||
+        (process.getuid && stat.uid !== process.getuid()))
+        throw fail('report_output_unavailable');
+}
+/** Write reviewed, local attachments only. No network, process execution, or config changes. */
+export function exportDiagnosticReport({ diagnostic, format = 'both', outputDir = 'reports' } = {}) {
+    const value = validateDiagnostic(diagnostic);
+    if (typeof format !== 'string' || !['md', 'json', 'both'].includes(format))
+        throw fail('report_invalid_format');
+    if (typeof outputDir !== 'string' || !outputDir || outputDir.length > 4096 || outputDir.includes('\0'))
+        throw fail('report_output_unavailable');
+    const directory = resolve(outputDir), createdDirectories = [], createdFiles = [];
+    const extensions = format === 'both' ? ['json', 'md'] : [format];
+    const files = extensions.map(extension => `diagnostic-${value.report_id}.${extension}`);
+    try {
+        privateDirectory(directory, createdDirectories);
+        for (let i = 0; i < files.length; i++) {
+            // Recheck parents before each exclusive creation; never follow a redirect
+            // or replace a pre-existing attachment, even a symlink or directory.
+            assertNoRedirectedAncestors(directory);
+            const path = join(directory, files[i]);
+            let fd;
+            try {
+                fd = openSync(path, 'wx', 0o600);
+                const stat = fstatSync(fd);
+                createdFiles.push({ path, dev: stat.dev, ino: stat.ino });
+                fchmodSync(fd, 0o600);
+                writeFileSync(fd, extensions[i] === 'json' ? JSON.stringify(value, null, 2) + '\n' : renderDiagnosticMarkdown(value));
+            }
+            finally {
+                if (fd !== undefined)
+                    closeSync(fd);
+            }
+        }
+        return { report_id: value.report_id, files, summary: { ...value.summary } };
+    }
+    catch (error) {
+        // Roll back only attachments created in this operation, preserving an
+        // existing collision and any concurrent replacement with a different inode.
+        for (const file of createdFiles.reverse()) {
+            try {
+                const current = lstatSync(file.path);
+                if (!current.isSymbolicLink() && current.dev === file.dev && current.ino === file.ino)
+                    unlinkSync(file.path);
+            }
+            catch { }
+        }
+        for (const dir of createdDirectories.reverse()) {
+            try {
+                rmdirSync(dir);
+            }
+            catch { }
+        }
+        throw fail(errorCode(error) === 'EEXIST' ? 'report_already_exists' : 'report_output_unavailable');
+    }
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,8 @@
+import { Router } from './core.ts';
+export declare function runtime(env?: NodeJS.ProcessEnv): {
+    router: Router;
+    mode: "decisions" | "fixture";
+    modelInfo: import("./model-info.ts").LoadedModelInfo;
+    disabledClients: import("./types.ts").Client[];
+    configuration: import("./config.ts").Configuration;
+};

package/dist/src/runtime.js

@@ -0,0 +1,22 @@
+import { Router, defaultPolicy } from './core.js';
+import { decisionsProvider, fixtureProvider } from './provider.js';
+import { loadConfiguration } from './config.js';
+import { resolveCatalog } from './catalog.js';
+import { loadModelInfo } from './model-info.js';
+import { assertPrivateStatePath } from './files.js';
+export function runtime(env = process.env) {
+    const value = env.ROUTER_PROVIDER ?? 'fixture';
+    if (value !== 'fixture' && value !== 'decisions')
+        throw new Error('invalid_provider_mode');
+    const mode = value;
+    if (mode === 'decisions') {
+        if (!env.ROUTER_LEDGER_PATH)
+            throw new Error('paid_mode_requires_ledger');
+        assertPrivateStatePath(env.ROUTER_LEDGER_PATH);
+    }
+    const modelInfo = loadModelInfo(env.APTLY_MODEL_INFO_PATH);
+    const catalog = resolveCatalog(env, modelInfo.facts);
+    const policy = { ...defaultPolicy, provider_id: mode, profiles: catalog.profiles, profile_descriptions: catalog.descriptions, catalog_version: catalog.version };
+    const router = new Router({ policy, provider: mode === 'fixture' ? fixtureProvider : decisionsProvider({ key: env.OPENAI_API_KEY, descriptions: catalog.descriptions }), ledgerPath: env.ROUTER_LEDGER_PATH });
+    return { router, mode, modelInfo, disabledClients: catalog.disabled_clients, configuration: loadConfiguration(env) };
+}

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer({ env }?: {
+    env?: NodeJS.ProcessEnv;
+}): McpServer;
+export declare function serve(options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<McpServer>;

package/dist/src/server.js

@@ -0,0 +1,80 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { pathToFileURL } from 'node:url';
+import { runtime } from './runtime.js';
+import { VERSION } from './version.js';
+import { hookInput, hookOutput } from './hook.js';
+import { resolveProvenance } from './provenance.js';
+import { loadConfiguration, loadHostContext } from './config.js';
+import { automaticHook, loadAutomaticHookPolicy } from './automatic-hook.js';
+const taskSchema = z.object({ summary: z.string().min(1).max(4000), operation: z.enum(['read_only', 'write', 'review', 'analysis']), context_sufficient: z.boolean() }).strict();
+const constraintsSchema = z.object({ model_pinned: z.boolean().optional(), effort_pinned: z.boolean().optional(), role_pinned: z.boolean().optional(), fork_inherits: z.boolean().optional(), provenance_verified: z.boolean().optional() }).strict();
+const hookSchema = { client: z.enum(['codex', 'claude']), event: z.record(z.string(), z.unknown()) };
+const content = (result) => ({ content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result });
+export function createServer({ env = process.env } = {}) {
+    const { router, mode, modelInfo, disabledClients } = runtime(env);
+    let lastAutomaticHook = null;
+    const server = new McpServer({ name: 'aptly', version: VERSION });
+    const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: mode === 'decisions' };
+    const evidence = (client, event) => {
+        const config = loadConfiguration(env);
+        const loaded = loadHostContext(config.context_path);
+        const precedence = resolveProvenance({ client, event, context: loaded.context });
+        return { config, loaded, precedence };
+    };
+    server.registerTool('get_routing_capabilities', { description: 'Advisory profile catalog, provider and local budget limits. No paid call.', annotations, inputSchema: {} }, async () => content({
+        ...router.capabilities(), provider: mode, hook_mode: loadConfiguration(env).mode,
+        precedence: 'per_call_effective_host_evidence_required', automatic_settings_discovery: false,
+        recommendation: { application: 'advisory_only', host_evidence_required: false, constraints: 'caller_declared_pins' },
+        model_information: { status: modelInfo.status, refresh: 'explicit_only', account_access_verified: false }, disabled_clients: disabledClients,
+        automatic_hook: { status: loadAutomaticHookPolicy(env.APTLY_HOOK_POLICY_PATH).reason, mode: loadAutomaticHookPolicy(env.APTLY_HOOK_POLICY_PATH).policy?.mode ?? 'disabled', host_settings_verified: false, last_result: lastAutomaticHook },
+    }));
+    server.registerTool('recommend_agent', {
+        description: 'Recommend an allowlisted profile for a supplied task only; never inspects host settings, spawns, or authorizes an agent. Optional constraints describe caller-declared choices to preserve; omitted flags are not claims about current host settings. Decisions mode may incur a bounded classification request.', annotations,
+        inputSchema: { request_id: z.string().min(1).max(96), client: z.enum(['codex', 'claude']), task: taskSchema, eligible_profile_ids: z.array(z.string()).min(1).max(20).optional(), constraints: constraintsSchema.optional() }
+    }, async (input) => content({ ...await router.advise(input), provider: mode }));
+    server.registerTool('get_routing_precedence', {
+        description: 'Explain preserved choices and unknown effective setting sources. Never classifies, reads a transcript, or changes permissions.', annotations: { ...annotations, openWorldHint: false }, inputSchema: hookSchema
+    }, async ({ client, event }) => {
+        const { precedence, loaded, config } = evidence(client, event);
+        return content({ ...precedence, evidence_status: loaded.reason, configuration_status: config.error ?? 'ok', application: 'advisory_only' });
+    });
+    server.registerTool('route_spawn_hook', {
+        description: 'Native PreToolUse Hook. An installed operator policy can select unpinned fresh-agent defaults through Decisions; otherwise the legacy evidence-gated path remains shadow by default. Explicit choices, role/fork/resume and failures preserve the call. Optional task never supplies policy.', annotations,
+        inputSchema: { ...hookSchema, task: taskSchema.optional() }
+    }, async ({ client, event, task }, extra) => {
+        if (env.APTLY_HOOK_POLICY_PATH !== undefined) {
+            const result = await automaticHook({ client, event, router, policyPath: env.APTLY_HOOK_POLICY_PATH, signal: extra.signal });
+            lastAutomaticHook = result.observation;
+            return { content: [{ type: 'text', text: JSON.stringify(result.output) }] };
+        }
+        const input = hookInput({ client, event, policy: router.policy });
+        if (!input)
+            return { content: [{ type: 'text', text: '{}' }] };
+        const before = evidence(client, event);
+        input.constraints = before.precedence.constraints;
+        if (task)
+            input.task = task;
+        const recommendation = await router.recommend(input);
+        // Revalidate binding, expiry, source fingerprints and operator configuration
+        // after an asynchronous provider call. A changed source cannot enable apply.
+        const after = evidence(client, event);
+        const apply = before.config.mode === 'apply' && !before.config.error && !after.config.error && after.config.mode === 'apply' &&
+            before.config.context_path === after.config.context_path && before.precedence.status === 'eligible' && after.precedence.status === 'eligible' &&
+            before.loaded.fingerprint === after.loaded.fingerprint && JSON.stringify(before.loaded.context) === JSON.stringify(after.loaded.context);
+        const output = hookOutput({ client, event, recommendation, mode: apply ? 'apply' : 'shadow', compatibilityVerified: apply, policy: router.policy });
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    });
+    return server;
+}
+export async function serve(options) { const server = createServer(options); await server.connect(new StdioServerTransport()); return server; }
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        await serve();
+    }
+    catch {
+        process.stderr.write('aptly: server_configuration_error\n');
+        process.exitCode = 1;
+    }
+}

package/dist/src/setup.d.ts

@@ -0,0 +1,22 @@
+type Client = 'codex' | 'claude';
+export interface SetupOptions {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    packageRoot?: string;
+    automatic?: boolean;
+    clients?: Client[];
+    mode?: 'defaults' | 'advisory';
+}
+export interface SetupClientResult {
+    client: Client;
+    status: 'configured' | 'unchanged' | 'removed' | 'skipped' | 'error';
+    codes: string[];
+    requires_hook_review?: boolean;
+}
+export interface SetupResult {
+    status: 'complete' | 'partial' | 'skipped';
+    clients: SetupClientResult[];
+}
+export declare function setupHosts(options?: SetupOptions): SetupResult;
+export declare function removeSetup(options?: SetupOptions): SetupResult;
+export {};