import type { AdapterEnvironmentCheck } from "@penclipai/adapter-utils";
/**
 * The fixed label a Test result shows when the probe runs on the local
 * Paperclip host. The label is a constant, so a local target check never
 * carries an environment ID, a config value, or a credential-derived string.
 */
export declare const ADAPTER_TEST_HOST_TARGET_LABEL = "Paperclip host";
/**
 * The allowlisted classification for a sandbox probe diagnostic. The call site
 * picks one fixed label from this set. The label never holds a copy of
 * untrusted probe text.
 *
 *   - `timeout`: the probe process did not finish before the deadline.
 *   - `auth_required`: the probe ran and reported that login is required.
 *   - `nonzero_exit`: the probe process exited with a non-zero exit code.
 *   - `spawn_error`: the probe process, or a setup step, threw before it ran.
 *   - `empty_output`: the probe produced no output.
 *   - `unexpected_output`: the probe ran and exited zero, but the output did
 *     not match the expected reply.
 */
export type SandboxProbeDiagnosticClassification = "timeout" | "auth_required" | "nonzero_exit" | "spawn_error" | "empty_output" | "unexpected_output";
/**
 * The safe structured fields a call site may add to a probe diagnostic. Each
 * field is a fixed shape, not free text. The helper drops any value that is not
 * safe.
 */
export interface SandboxProbeDiagnosticFields {
    exitCode?: number | null;
    errorClass?: string | null;
}
/**
 * Read the class name of a thrown value for a safe probe diagnostic. The
 * function returns the constructor name of an `Error`, or `null` for any other
 * value. The name is a bounded identifier, not a copy of the error message, so
 * it carries no untrusted probe text.
 */
export declare function classifyThrownErrorClass(err: unknown): string | null;
/**
 * Send a sandbox probe or config materialization diagnostic to the server log.
 *
 * Three Test-lane call sites use this helper:
 *   - the Claude CLI Test lane (`test.ts`),
 *   - the Claude ACP Test lane (`acp.ts`),
 *   - the managed-config materialization step (`claude-config.ts`).
 *
 * Contract: no untrusted text reaches the log. The helper logs only the fixed
 * context string, one allowlisted classification, and safe structured fields.
 * The safe fields are the process exit code and a sanitized error class name.
 * The helper never logs raw probe stdout, raw stderr, or a raw thrown-error
 * message. A call site must never copy raw probe text into a Test-result check,
 * because the user interface renders check text.
 *
 * @param context A short fixed description of the failed step. It carries no
 *   untrusted text.
 * @param classification One allowlisted label that the call site derives from
 *   the probe state. It carries no untrusted text.
 * @param fields Optional safe structured fields, such as the exit code.
 */
export declare function logSandboxProbeDiagnostic(context: string, classification: SandboxProbeDiagnosticClassification, fields?: SandboxProbeDiagnosticFields): void;
/**
 * Normalize an untrusted login URL for a Test-result hint.
 *
 * The extractor reads the URL from raw sandbox stdout or stderr, so the value is
 * untrusted. The function accepts the URL only when every rule holds:
 *   - the protocol is `https`,
 *   - the host equals or ends with an allowlisted Claude or Anthropic host,
 *   - the URL has no user, password, or port,
 *   - the URL has no query and no fragment.
 *
 * The function returns the normalized URL string, or `null` when any rule
 * fails. The caller shows a fixed `claude login` hint when the function returns
 * `null`.
 */
export declare function normalizeClaudeLoginUrl(raw: string | null | undefined): string | null;
/**
 * Build the fixed auth-required hint for a Test-result check. When the login URL
 * normalizes to a safe value, the hint names it. Otherwise the hint tells the
 * operator to run `claude login`.
 */
export declare function buildClaudeLoginRequiredHint(loginUrl: string | null | undefined): string;
/**
 * Resolve the label a Test result shows for the probed target. A remote target
 * uses the authorized environment name. A remote target with no name uses a
 * fixed generic label. A local target uses the fixed host label. The function
 * never returns an environment ID, a config value, or a credential-derived
 * string.
 */
export declare function resolveAdapterTestTargetLabel(input: {
    targetIsRemote: boolean;
    environmentName: string | null | undefined;
}): string;
/**
 * Build the target check every Test result carries, so the result names the
 * target it probed. Both the Claude CLI Test lane and the Claude ACP Test lane
 * use this builder. The check text carries only the authorized environment
 * label or the fixed host label.
 */
export declare function buildAdapterTestTargetCheck(input: {
    targetIsRemote: boolean;
    environmentName: string | null | undefined;
}): AdapterEnvironmentCheck;
//# sourceMappingURL=probe-diagnostics.d.ts.map