@shardlink/agent-sdk 0.1.0

package/dist/modules/degradation.js

@@ -0,0 +1,205 @@
+/**
+ * Graceful degradation contract.
+ *
+ * When things go wrong — lease expires mid-task, spend cap hits, platform
+ * degrades, task times out — the agent needs a predictable, user-declared
+ * policy for how to react. The {@link DegradationContract} describes those
+ * choices; {@link DegradationEnforcer} applies them against a running
+ * lease manager / task scheduler.
+ *
+ * This module does not poll the server or send requests on its own. It
+ * wires together the state signals the rest of the SDK already produces
+ * (lease events from {@link LeaseManager}, timers, platform-status probes
+ * from {@link DiagnosticsClient}) and calls back into the host app.
+ *
+ * @packageDocumentation
+ */
+/** Default contract — conservative, pause-and-retry oriented. */
+export const DEFAULT_DEGRADATION = Object.freeze({
+    leaseExpiry: "pause_and_retry",
+    spendCapHit: "pause_new_claims",
+    platformDegraded: "retry_with_backoff",
+    taskTimeoutMs: 5 * 60_000,
+    taskTimeoutAction: "release_claim"
+});
+/**
+ * Applies a {@link DegradationContract} to the lifecycle signals emitted by
+ * the rest of the SDK. Each signal maps to exactly one handler invocation
+ * so the host app can reliably react.
+ *
+ * @example
+ * ```ts
+ * const enforcer = new DegradationEnforcer({
+ *   contract: { ...DEFAULT_DEGRADATION, spendCapHit: "shutdown" },
+ *   handlers: {
+ *     pauseClaims: () => scheduler.pause(),
+ *     resumeClaims: () => scheduler.resume(),
+ *     requestLeaseExtension: () => leaseClient.request(...),
+ *     shutdown: () => process.exit(0)
+ *   }
+ * });
+ *
+ * lease.onBudgetThreshold(100, () => enforcer.onSpendCapHit(lease.status()));
+ * ```
+ */
+export class DegradationEnforcer {
+    contract;
+    handlers;
+    inFlight = new Map();
+    paused = false;
+    constructor(options) {
+        this.contract = options.contract ?? DEFAULT_DEGRADATION;
+        this.handlers = options.handlers;
+    }
+    /** Mark a task as in-flight so timeout detection can watch it. */
+    trackClaim(taskId) {
+        const existing = this.inFlight.get(taskId);
+        if (existing?.timer)
+            clearTimeout(existing.timer);
+        const record = { taskId, claimedAt: Date.now() };
+        record.timer = setTimeout(() => void this.onTaskTimeout(taskId), this.contract.taskTimeoutMs);
+        this.inFlight.set(taskId, record);
+    }
+    /** Clear a task (because it completed). */
+    completeClaim(taskId) {
+        const record = this.inFlight.get(taskId);
+        if (record?.timer)
+            clearTimeout(record.timer);
+        this.inFlight.delete(taskId);
+    }
+    /** Wire this into {@link LeaseManager.enableAutoRenew}'s `onFailed` or to a `lease_expiring` handler. */
+    async onLeaseExpiring(snapshot) {
+        const ctx = {
+            reason: "lease_expiring",
+            strategy: this.contract.leaseExpiry,
+            details: snapshot
+        };
+        switch (this.contract.leaseExpiry) {
+            case "pause_and_retry":
+                await this.pause(ctx);
+                break;
+            case "abort_gracefully":
+                await this.pause(ctx);
+                await this.handlers.shutdown?.({ ...ctx, reason: "lease_expiring" });
+                break;
+            case "request_extension":
+                await this.pause(ctx);
+                await this.handlers.requestLeaseExtension?.(ctx);
+                break;
+        }
+    }
+    /** Call after a successful lease renewal so claim flow resumes. */
+    async onLeaseRenewed(snapshot) {
+        if (!this.paused)
+            return;
+        await this.resume({
+            reason: "lease_expiring",
+            strategy: this.contract.leaseExpiry,
+            details: snapshot
+        });
+    }
+    /** Wire to {@link LeaseManager.onBudgetThreshold}(100). */
+    async onSpendCapHit(snapshot) {
+        const ctx = {
+            reason: "spend_cap_hit",
+            strategy: this.contract.spendCapHit,
+            details: snapshot
+        };
+        switch (this.contract.spendCapHit) {
+            case "pause_new_claims":
+                await this.pause(ctx);
+                break;
+            case "complete_current_only":
+                await this.pause(ctx);
+                if (this.inFlight.size === 0) {
+                    await this.handlers.shutdown?.(ctx);
+                }
+                break;
+            case "shutdown":
+                await this.pause(ctx);
+                await this.handlers.shutdown?.(ctx);
+                break;
+        }
+    }
+    /** Wire to {@link DiagnosticsClient.platformStatus} when `ok: false`. */
+    async onPlatformDegraded(details) {
+        const ctx = {
+            reason: "platform_degraded",
+            strategy: this.contract.platformDegraded,
+            ...(details ? { details } : {})
+        };
+        switch (this.contract.platformDegraded) {
+            case "retry_with_backoff":
+                await this.pause(ctx);
+                break;
+            case "switch_workspace":
+                await this.pause(ctx);
+                await this.handlers.switchWorkspace?.(ctx);
+                break;
+            case "hibernate":
+                await this.pause(ctx);
+                await this.handlers.hibernate?.(ctx);
+                break;
+        }
+    }
+    /** Host calls this when the platform recovers (next successful heartbeat). */
+    async onPlatformRecovered() {
+        if (!this.paused)
+            return;
+        await this.resume({
+            reason: "platform_recovered",
+            strategy: this.contract.platformDegraded
+        });
+    }
+    async onTaskTimeout(taskId) {
+        const record = this.inFlight.get(taskId);
+        if (!record)
+            return;
+        this.inFlight.delete(taskId);
+        const ctx = {
+            reason: "task_timeout",
+            strategy: this.contract.taskTimeoutAction,
+            details: { taskId, claimedAt: record.claimedAt }
+        };
+        switch (this.contract.taskTimeoutAction) {
+            case "release_claim":
+                await this.handlers.releaseTaskClaim?.(taskId, ctx);
+                break;
+            case "mark_failed":
+                await this.handlers.markTaskFailed?.(taskId, ctx);
+                break;
+            case "request_extension":
+                await this.handlers.requestLeaseExtension?.(ctx);
+                break;
+        }
+    }
+    async pause(ctx) {
+        if (this.paused)
+            return;
+        this.paused = true;
+        await this.handlers.pauseClaims?.(ctx);
+    }
+    async resume(ctx) {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        await this.handlers.resumeClaims?.(ctx);
+    }
+    /** Currently accepting new claims? */
+    isAcceptingClaims() {
+        return !this.paused;
+    }
+    /** How many tasks are tracked as in-flight right now. */
+    inFlightCount() {
+        return this.inFlight.size;
+    }
+    /** Clear all timers — call on shutdown. */
+    dispose() {
+        for (const record of this.inFlight.values()) {
+            if (record.timer)
+                clearTimeout(record.timer);
+        }
+        this.inFlight.clear();
+    }
+}
+//# sourceMappingURL=degradation.js.map

package/dist/modules/degradation.js.map

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

package/dist/modules/diagnostics-checks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure preflight checks + remediation helpers for {@link DiagnosticsClient}.
+ *
+ * Extracted from `diagnostics.ts` to keep each SDK module file under the
+ * 400-line ceiling (CLAUDE.md §"Agent DX Rules"). These are the synchronous,
+ * `this`-free portions of the preflight battery — the lease / billing /
+ * capabilities / sandbox checks and the auto-fix suggestion logic. The async,
+ * network-touching checks (`checkAuth`, `checkConnectivity`, `checkPlatform`)
+ * stay on the client where they have access to the HTTP context.
+ *
+ * Behavior is unchanged: `diagnostics.ts` calls these functions in place of
+ * the former private methods, so {@link DiagnosticsClient.preflight} produces
+ * the identical report.
+ *
+ * @internal These helpers are not part of the SDK's published API surface —
+ * they are re-used by `diagnostics.ts` only. Consume {@link DiagnosticsClient}
+ * (exported from the package root and `@shardlink/agent-sdk/diagnostics`).
+ *
+ * @packageDocumentation
+ */
+import type { AutoFix, CheckResult, PreflightCheckName, PreflightInput } from "./diagnostics-types.js";
+/** Lease-state check — `warn` when no snapshot is supplied. */
+export declare function checkLease(input: PreflightInput): CheckResult;
+/** Billing-envelope check — `warn` when no envelope is supplied. */
+export declare function checkBilling(input: PreflightInput): CheckResult;
+/** Declared-capability sanity check — `warn` when essentials are missing. */
+export declare function checkCapabilities(input: PreflightInput): CheckResult;
+/** Trust-tier policy check — `warn` when no policy/snapshot is supplied. */
+export declare function checkSandbox(input: PreflightInput): CheckResult;
+/** Map a failed check to a programmatic remediation hint, when one exists. */
+export declare function suggestAutoFix(check: PreflightCheckName, result: CheckResult): AutoFix | null;
+//# sourceMappingURL=diagnostics-checks.d.ts.map

package/dist/modules/diagnostics-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-checks.d.ts","sourceRoot":"","sources":["../../src/modules/diagnostics-checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,cAAc,EACf,MAAM,wBAAwB,CAAC;AAEhC,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CA6B7D;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CA8B/D;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAcpE;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAuE/D;AAoED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,GAAG,IAAI,CAQ7F"}

package/dist/modules/diagnostics-checks.js

@@ -0,0 +1,231 @@
+/**
+ * Pure preflight checks + remediation helpers for {@link DiagnosticsClient}.
+ *
+ * Extracted from `diagnostics.ts` to keep each SDK module file under the
+ * 400-line ceiling (CLAUDE.md §"Agent DX Rules"). These are the synchronous,
+ * `this`-free portions of the preflight battery — the lease / billing /
+ * capabilities / sandbox checks and the auto-fix suggestion logic. The async,
+ * network-touching checks (`checkAuth`, `checkConnectivity`, `checkPlatform`)
+ * stay on the client where they have access to the HTTP context.
+ *
+ * Behavior is unchanged: `diagnostics.ts` calls these functions in place of
+ * the former private methods, so {@link DiagnosticsClient.preflight} produces
+ * the identical report.
+ *
+ * @internal These helpers are not part of the SDK's published API surface —
+ * they are re-used by `diagnostics.ts` only. Consume {@link DiagnosticsClient}
+ * (exported from the package root and `@shardlink/agent-sdk/diagnostics`).
+ *
+ * @packageDocumentation
+ */
+import { SandboxPolicy } from "./sandbox.js";
+/** Lease-state check — `warn` when no snapshot is supplied. */
+export function checkLease(input) {
+    if (!input.lease) {
+        return { status: "warn", message: "lease snapshot not provided" };
+    }
+    if (input.lease.status === "revoked") {
+        return {
+            status: "fail",
+            message: "lease is revoked",
+            details: input.lease
+        };
+    }
+    if (input.lease.status === "expired") {
+        return { status: "fail", message: "lease has expired", details: input.lease };
+    }
+    const now = Date.now();
+    if (input.lease.expiresAt !== undefined) {
+        const expiresAt = typeof input.lease.expiresAt === "number"
+            ? input.lease.expiresAt
+            : Date.parse(input.lease.expiresAt);
+        if (!Number.isNaN(expiresAt) && expiresAt - now < 60_000) {
+            return {
+                status: "warn",
+                message: `lease expires in ${Math.max(0, expiresAt - now)}ms`,
+                details: input.lease
+            };
+        }
+    }
+    return { status: "pass", details: input.lease };
+}
+/** Billing-envelope check — `warn` when no envelope is supplied. */
+export function checkBilling(input) {
+    if (!input.billing) {
+        return { status: "warn", message: "billing envelope not provided" };
+    }
+    if (input.billing.status && input.billing.status !== "active") {
+        return {
+            status: "fail",
+            message: `envelope ${input.billing.status}`,
+            details: input.billing
+        };
+    }
+    const authorized = input.billing.authorizedAmountUsdCents ?? 0;
+    const consumed = input.billing.consumedAmountUsdCents ?? 0;
+    const headroom = authorized - consumed;
+    const minHeadroom = input.minBudgetHeadroomUsdCents ?? 100;
+    if (headroom <= 0) {
+        return {
+            status: "fail",
+            message: "spend envelope depleted",
+            details: input.billing
+        };
+    }
+    if (headroom < minHeadroom) {
+        return {
+            status: "warn",
+            message: `low spend headroom (${headroom}¢ < ${minHeadroom}¢ min)`,
+            details: input.billing
+        };
+    }
+    return { status: "pass", details: input.billing };
+}
+/** Declared-capability sanity check — `warn` when essentials are missing. */
+export function checkCapabilities(input) {
+    if (!input.supportedActions || input.supportedActions.length === 0) {
+        return { status: "warn", message: "supportedActions not declared" };
+    }
+    const essentials = ["claim_task", "complete_task"];
+    const missing = essentials.filter((action) => !input.supportedActions?.includes(action));
+    if (missing.length > 0) {
+        return {
+            status: "warn",
+            message: `missing actions: ${missing.join(", ")}`,
+            details: input.supportedActions
+        };
+    }
+    return { status: "pass", details: input.supportedActions };
+}
+/** Trust-tier policy check — `warn` when no policy/snapshot is supplied. */
+export function checkSandbox(input) {
+    if (!input.sandbox) {
+        return { status: "warn", message: "sandbox policy not provided" };
+    }
+    const policy = input.sandbox instanceof SandboxPolicy ? input.sandbox : new SandboxPolicy(input.sandbox);
+    const snap = policy.getSnapshot();
+    const tier = policy.effectivePolicy().tier;
+    const progression = policy.progressReport();
+    if (snap.qualification.blockedReasons.length > 0) {
+        return {
+            status: "fail",
+            message: `blocked qualifications: ${snap.qualification.blockedReasons.join(", ")}`,
+            details: { tier, blockedReasons: snap.qualification.blockedReasons, progression }
+        };
+    }
+    if (input.workspaceEntry) {
+        const eligibility = policy.canJoinWorkspace(input.workspaceEntry);
+        if (!eligibility.eligible) {
+            return {
+                status: "fail",
+                message: eligibility.message ?? `workspace ineligible (${eligibility.reason})`,
+                details: { tier, eligibility, progression }
+            };
+        }
+        if (eligibility.reason === "suspended_capability") {
+            return {
+                status: "warn",
+                message: eligibility.message ?? "workspace has suspended capabilities",
+                details: { tier, eligibility }
+            };
+        }
+    }
+    if (typeof input.prospectiveSpendUsdCents === "number") {
+        const alreadySpent = input.spentTodayUsdCents ?? 0;
+        if (!policy.canSpend(input.prospectiveSpendUsdCents, alreadySpent)) {
+            const cap = policy.effectivePolicy().dailySpendCapUsdCents;
+            return {
+                status: "fail",
+                message: `daily spend cap exceeded (${alreadySpent + input.prospectiveSpendUsdCents}¢ > ${cap}¢)`,
+                details: {
+                    tier,
+                    cap,
+                    spentTodayUsdCents: alreadySpent,
+                    prospectiveSpendUsdCents: input.prospectiveSpendUsdCents,
+                    progression
+                }
+            };
+        }
+    }
+    if (typeof input.claimsInLastHour === "number") {
+        if (!policy.withinClaimRate(input.claimsInLastHour)) {
+            const limit = policy.effectivePolicy().perHourTaskClaims;
+            return {
+                status: "warn",
+                message: `per-hour claim rate reached (${input.claimsInLastHour} >= ${limit})`,
+                details: {
+                    tier,
+                    limit,
+                    observed: input.claimsInLastHour,
+                    progression
+                }
+            };
+        }
+    }
+    return { status: "pass", details: { tier, progression } };
+}
+const AUTO_FIX_TEMPLATES = {
+    auth: {
+        action: "refresh_session",
+        description: "Refresh wallet session via auth.repeatWalletAccess() or re-sign challenge."
+    },
+    lease: {
+        action: "request_lease",
+        description: "Call leases.request() or LeaseManager.enableAutoRenew() to request a new lease."
+    },
+    billing: {
+        action: "top_up_envelope",
+        description: "Fund a new spend envelope via billing.createEnvelope() or request a delegated grant."
+    },
+    connectivity: {
+        action: "retry_with_backoff",
+        description: (r) => `Network unreachable: ${r.message ?? ""}. Retry with exponential backoff.`
+    },
+    platform: {
+        action: "wait_for_platform",
+        description: "Platform not ready; back off and retry heartbeat until /health/ready returns ok."
+    },
+    capabilities: null,
+    sandbox: {
+        action: "upgrade_trust_tier",
+        description: (r) => describeSandboxRemediation(r)
+    }
+};
+function describeSandboxRemediation(result) {
+    const details = result.details;
+    const progression = details?.progression;
+    if (details?.eligibility?.reason === "requires_higher_proof") {
+        return "Complete wallet verification (EIP-4361 sign-in) to raise proof level to P2.";
+    }
+    if (details?.eligibility?.reason === "invite_only") {
+        return "Workspace is invite-only; request an invite from its governor.";
+    }
+    if (details?.blockedReasons && details.blockedReasons.length > 0) {
+        return `Resolve passport-level blockers: ${details.blockedReasons.join(", ")}.`;
+    }
+    if (!progression) {
+        return "Trust tier restricts this action; review SandboxPolicy.progressReport() for criteria.";
+    }
+    if (progression.to === null) {
+        return "Agent is at the highest trust tier; no further upgrade path.";
+    }
+    const unmet = progression.criteria.filter((c) => !c.met);
+    if (unmet.length === 0) {
+        return `All criteria met to promote from ${progression.from} → ${progression.to}; refresh passport to sync server-side tier.`;
+    }
+    const pct = Math.round(progression.progress * 100);
+    return `Progress ${pct}% from ${progression.from} → ${progression.to}; remaining: ${unmet
+        .map((c) => c.label)
+        .join("; ")}.`;
+}
+/** Map a failed check to a programmatic remediation hint, when one exists. */
+export function suggestAutoFix(check, result) {
+    const template = AUTO_FIX_TEMPLATES[check];
+    if (!template)
+        return null;
+    const description = typeof template.description === "function"
+        ? template.description(result)
+        : template.description;
+    return { check, action: template.action, description };
+}
+//# sourceMappingURL=diagnostics-checks.js.map

package/dist/modules/diagnostics-checks.js.map

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

package/dist/modules/diagnostics-types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared type definitions for the diagnostics + preflight client.
+ *
+ * Extracted from `diagnostics.ts` so both the client (`diagnostics.ts`) and
+ * the pure check helpers (`diagnostics-checks.ts`) can reference them without
+ * a circular import, and so each file stays under the 400-line SDK module
+ * ceiling (CLAUDE.md §"Agent DX Rules").
+ *
+ * The public API is unchanged: `diagnostics.ts` re-exports every type below,
+ * so they remain importable from `@shardlink/agent-sdk` and
+ * `@shardlink/agent-sdk/diagnostics` exactly as before.
+ *
+ * @packageDocumentation
+ */
+import type { HttpContext } from "../utils.js";
+import type { DiscoveryClient } from "./discovery.js";
+import type { LeaseSnapshot } from "./lease-manager.js";
+import type { SandboxPolicy, AgentSnapshot } from "./sandbox.js";
+import type { WorkspaceDirectoryEntry } from "../types.js";
+/** Status of an individual preflight check. */
+export type CheckStatus = "pass" | "warn" | "fail";
+/** A single preflight check result. */
+export interface CheckResult {
+    status: CheckStatus;
+    message?: string;
+    details?: unknown;
+}
+/** Full preflight report. */
+export interface PreflightResult {
+    ready: boolean;
+    checks: {
+        auth: CheckResult;
+        lease: CheckResult;
+        billing: CheckResult;
+        connectivity: CheckResult;
+        capabilities: CheckResult;
+        platform: CheckResult;
+        sandbox: CheckResult;
+    };
+    /** Human-readable issue strings (empty when `ready: true`). */
+    issues: string[];
+    /** Programmatic remediation hints. */
+    autoFixable: AutoFix[];
+}
+/** Name of an individual preflight check (a key of {@link PreflightResult.checks}). */
+export type PreflightCheckName = keyof PreflightResult["checks"];
+/** Machine-readable remediation hint. */
+export interface AutoFix {
+    check: PreflightCheckName;
+    action: string;
+    description: string;
+}
+/** Platform health projection. */
+export interface PlatformHealth {
+    ok: boolean;
+    depth: "shallow" | "deep";
+    details: Record<string, {
+        ok: boolean;
+        message?: string;
+    }>;
+}
+/** Input accepted by `DiagnosticsClient.preflight`. */
+export interface PreflightInput {
+    /** Current lease snapshot. Omit to skip the lease check (status: warn). */
+    lease?: LeaseSnapshot;
+    /** Declared supported actions so capabilities can be sanity-checked. */
+    supportedActions?: string[];
+    /** Billing-side envelope snapshot so spend headroom is visible. */
+    billing?: {
+        envelopeId?: string;
+        authorizedAmountUsdCents?: number;
+        consumedAmountUsdCents?: number;
+        status?: "active" | "exhausted" | "revoked" | "expired";
+    };
+    /** How much budget headroom (in authorized USD cents) is considered healthy. */
+    minBudgetHeadroomUsdCents?: number;
+    /**
+     * Trust-tier policy evaluator. Pass a pre-built {@link SandboxPolicy} or
+     * an {@link AgentSnapshot} — the latter will be wrapped in a default
+     * policy. Omit to skip the sandbox check (status: warn).
+     */
+    sandbox?: SandboxPolicy | AgentSnapshot;
+    /**
+     * Optional workspace directory entry — if present, the sandbox check
+     * calls `canJoinWorkspace` and reports ineligibility as fail.
+     */
+    workspaceEntry?: WorkspaceDirectoryEntry;
+    /**
+     * Prospective USD-cent spend the agent is about to authorize. The
+     * sandbox check calls `SandboxPolicy.canSpend` with this +
+     * `spentTodayUsdCents` against the tier's daily cap.
+     */
+    prospectiveSpendUsdCents?: number;
+    /** USD cents already consumed today — defaults to `0`. */
+    spentTodayUsdCents?: number;
+    /**
+     * Observed task-claim count in the last rolling hour. If present and
+     * over the tier's per-hour cap, the sandbox check returns `warn`.
+     */
+    claimsInLastHour?: number;
+}
+/** Log level for `DiagnosticsClient.log`. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** Destination that receives structured diagnostic logs. */
+export type LogSink = (entry: {
+    level: LogLevel;
+    message: string;
+    meta?: Record<string, unknown>;
+    at: number;
+}) => void;
+/** Options for the diagnostics client. */
+export interface DiagnosticsClientOptions {
+    http: HttpContext;
+    discovery: DiscoveryClient;
+    /** Optional explicit sink — defaults to `console.log` JSON line. */
+    logSink?: LogSink;
+}
+//# sourceMappingURL=diagnostics-types.d.ts.map

package/dist/modules/diagnostics-types.d.ts.map

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

package/dist/modules/diagnostics-types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared type definitions for the diagnostics + preflight client.
+ *
+ * Extracted from `diagnostics.ts` so both the client (`diagnostics.ts`) and
+ * the pure check helpers (`diagnostics-checks.ts`) can reference them without
+ * a circular import, and so each file stays under the 400-line SDK module
+ * ceiling (CLAUDE.md §"Agent DX Rules").
+ *
+ * The public API is unchanged: `diagnostics.ts` re-exports every type below,
+ * so they remain importable from `@shardlink/agent-sdk` and
+ * `@shardlink/agent-sdk/diagnostics` exactly as before.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=diagnostics-types.js.map

package/dist/modules/diagnostics-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-types.js","sourceRoot":"","sources":["../../src/modules/diagnostics-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}