@xenosystem/agent-sdk 0.8.12

package/dist/hosted/index.d.cts

@@ -0,0 +1,490 @@
+type XenoJsonPrimitive = string | number | boolean | null;
+type XenoJsonValue = XenoJsonPrimitive | XenoJsonObject | XenoJsonValue[];
+interface XenoJsonObject {
+    [key: string]: XenoJsonValue;
+}
+declare const XENO_HOSTED_ENVIRONMENT_SCHEMA_VERSION: 1;
+declare const XENO_HOSTED_RUN_SCHEMA_VERSION: 1;
+declare const XENO_HOSTED_EVENT_SCHEMA_VERSION: 1;
+declare const XENO_HOSTED_TRIGGER_SCHEMA_VERSION: 1;
+type XenoHostedOs = "linux" | "windows" | "macos";
+type XenoHostedArchitecture = "x64" | "arm64";
+type XenoHostedRunStatus = "queued" | "provisioning" | "running" | "waiting_for_approval" | "paused" | "completed" | "failed" | "cancelled" | "expired";
+interface XenoHostedRepositorySource {
+    provider: "github" | "gitlab" | "bitbucket" | "generic-git" | `custom:${string}`;
+    repository: string;
+    ref: string;
+    commit?: string;
+    subdirectory?: string;
+    shallow?: boolean;
+}
+interface XenoHostedImageReference {
+    reference: string;
+    digest: string;
+    os: XenoHostedOs;
+    architecture: XenoHostedArchitecture;
+}
+interface XenoHostedSetupStep {
+    id: string;
+    command: string;
+    workingDirectory?: string;
+    timeoutMs: number;
+    network: "deny" | "environment-policy";
+}
+interface XenoHostedCacheMount {
+    key: string;
+    path: string;
+    restoreKeys?: string[];
+    readOnly?: boolean;
+    maxBytes?: number;
+}
+interface XenoHostedNetworkDestination {
+    host: string;
+    ports?: number[];
+    protocols?: Array<"http" | "https" | "ssh" | "git">;
+    reason: string;
+}
+interface XenoHostedNetworkPolicy {
+    default: "deny";
+    dns: "deny" | "allow-resolved-destinations";
+    destinations: XenoHostedNetworkDestination[];
+    maxResponseBytes?: number;
+}
+interface XenoHostedSecretProjection {
+    ref: string;
+    target: {
+        kind: "environment";
+        name: string;
+    } | {
+        kind: "file";
+        path: string;
+    };
+    required: boolean;
+    exposeToChildProcesses: boolean;
+}
+interface XenoHostedResourceLimits {
+    cpuMillis: number;
+    memoryBytes: number;
+    diskBytes: number;
+    processLimit: number;
+    wallTimeMs: number;
+}
+interface XenoHostedRetentionPolicy {
+    workspaceTtlMs: number;
+    eventTtlMs: number;
+    artifactTtlMs: number;
+    wipeWorkspace: boolean;
+}
+interface XenoHostedEnvironmentManifestPayload {
+    schemaVersion: typeof XENO_HOSTED_ENVIRONMENT_SCHEMA_VERSION;
+    kind: "xeno-hosted-environment";
+    environmentId: string;
+    revision: number;
+    createdAt: string;
+    createdBy: string;
+    workspaceId: string;
+    name: string;
+    repository: XenoHostedRepositorySource;
+    image: XenoHostedImageReference;
+    setup: XenoHostedSetupStep[];
+    caches: XenoHostedCacheMount[];
+    network: XenoHostedNetworkPolicy;
+    secrets: XenoHostedSecretProjection[];
+    resources: XenoHostedResourceLimits;
+    retention: XenoHostedRetentionPolicy;
+    labels: Record<string, string>;
+}
+interface XenoHostedEnvironmentManifest extends XenoHostedEnvironmentManifestPayload {
+    checksum: {
+        algorithm: "sha256";
+        value: string;
+    };
+}
+interface XenoHostedAuthority {
+    filesystem: "read" | "workspace-write";
+    network: "deny" | "environment-policy";
+    externalActions: "deny" | "approval-required";
+    secretRefs: string[];
+}
+interface XenoHostedBudget {
+    maxCredits: number;
+    maxTokens?: number;
+    maxDurationMs: number;
+    maxToolCalls?: number;
+}
+interface XenoHostedQuotaLease {
+    leaseId: string;
+    principalId: string;
+    workspaceId: string;
+    acquiredAt: string;
+    expiresAt: string;
+    concurrencySlot: number;
+    maxConcurrentRuns: number;
+}
+interface XenoHostedRunRequest {
+    schemaVersion: typeof XENO_HOSTED_RUN_SCHEMA_VERSION;
+    kind: "xeno-hosted-run-request";
+    clientRequestId: string;
+    idempotencyKey: string;
+    requestedAt: string;
+    requestedBy: string;
+    workspaceId: string;
+    environment: {
+        environmentId: string;
+        revision: number;
+        checksum: string;
+    };
+    prompt: string;
+    model?: string;
+    effort?: string;
+    agentProfile?: string;
+    authority: XenoHostedAuthority;
+    budget: XenoHostedBudget;
+    handoffId?: string;
+    previousRunId?: string;
+    artifactIds?: string[];
+    metadata?: Record<string, XenoJsonValue>;
+}
+interface XenoHostedRunRecord {
+    schemaVersion: typeof XENO_HOSTED_RUN_SCHEMA_VERSION;
+    kind: "xeno-hosted-run";
+    hostedRunId: string;
+    request: XenoHostedRunRequest;
+    status: XenoHostedRunStatus;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    endedAt?: string;
+    statusReason?: string;
+    quotaLease?: XenoHostedQuotaLease;
+    localRunId?: string;
+    branch?: string;
+    pullRequest?: {
+        provider: string;
+        repository: string;
+        number: number;
+        url: string;
+    };
+    artifactIds: string[];
+    lastSequence: number;
+}
+interface XenoHostedEventRecord {
+    schemaVersion: typeof XENO_HOSTED_EVENT_SCHEMA_VERSION;
+    kind: "xeno-hosted-event";
+    eventId: string;
+    streamId: string;
+    sequence: number;
+    timestamp: string;
+    type: string;
+    actorId: string;
+    idempotencyKey?: string;
+    payload: Record<string, XenoJsonValue>;
+    previousHash: string | null;
+    hash: string;
+}
+interface XenoHostedReplayCursor {
+    streamId: string;
+    afterSequence: number;
+    lastHash?: string;
+}
+interface XenoHostedReplayPage {
+    schemaVersion: typeof XENO_HOSTED_EVENT_SCHEMA_VERSION;
+    streamId: string;
+    events: XenoHostedEventRecord[];
+    cursor: XenoHostedReplayCursor;
+    hasMore: boolean;
+}
+type XenoHostedTriggerKind = "api" | "schedule" | "github.issue" | "github.pull_request" | "github.comment" | "gitlab.issue" | "gitlab.merge_request" | "gitlab.note" | "slack.message" | "teams.message" | "linear.issue" | "jira.issue" | "jira.comment";
+interface XenoHostedTriggerDefinition {
+    schemaVersion: typeof XENO_HOSTED_TRIGGER_SCHEMA_VERSION;
+    kind: "xeno-hosted-trigger";
+    triggerId: string;
+    workspaceId: string;
+    name: string;
+    enabled: boolean;
+    source: {
+        kind: XenoHostedTriggerKind;
+        installationRef?: string;
+        channelRef?: string;
+        schedule?: string;
+        filters: Record<string, string[]>;
+    };
+    environment: {
+        environmentId: string;
+        revision: number;
+        checksum: string;
+    };
+    promptTemplate: string;
+    agentProfile?: string;
+    authority: XenoHostedAuthority;
+    budget: XenoHostedBudget;
+    createdAt: string;
+    createdBy: string;
+}
+interface XenoHostedTriggerDelivery {
+    schemaVersion: typeof XENO_HOSTED_TRIGGER_SCHEMA_VERSION;
+    kind: "xeno-hosted-trigger-delivery";
+    deliveryId: string;
+    triggerId: string;
+    source: XenoHostedTriggerKind;
+    externalDeliveryId: string;
+    receivedAt: string;
+    verifiedAt: string;
+    bodySha256: string;
+    principal: {
+        id: string;
+        displayName?: string;
+    };
+    repository?: {
+        provider: string;
+        repository: string;
+        ref?: string;
+    };
+    subject: {
+        type: string;
+        id: string;
+        title?: string;
+        url?: string;
+    };
+    message?: string;
+    attributes: Record<string, string>;
+    idempotencyKey: string;
+}
+interface XenoHostedWebhookVerification {
+    valid: boolean;
+    source: "github" | "gitlab" | "slack" | "teams" | "linear" | "jira" | "xeno";
+    bodySha256: string;
+    timestamp?: string;
+    error?: "missing-signature" | "invalid-signature" | "stale-timestamp" | "invalid-timestamp";
+}
+declare function createXenoHostedEnvironmentManifest(payload: Omit<XenoHostedEnvironmentManifestPayload, "schemaVersion" | "kind">): XenoHostedEnvironmentManifest;
+declare function verifyXenoHostedEnvironmentManifest(manifest: XenoHostedEnvironmentManifest): {
+    valid: boolean;
+    errors: string[];
+};
+declare function createXenoHostedEvent(options: {
+    streamId: string;
+    sequence: number;
+    type: string;
+    actorId: string;
+    payload?: Record<string, XenoJsonValue>;
+    previous?: XenoHostedEventRecord;
+    idempotencyKey?: string;
+    timestamp?: string;
+    eventId?: string;
+}): XenoHostedEventRecord;
+declare function verifyXenoHostedEventChain(events: readonly XenoHostedEventRecord[], cursor?: XenoHostedReplayCursor): {
+    valid: boolean;
+    errors: string[];
+    cursor: XenoHostedReplayCursor | null;
+};
+declare function hostedEnvironmentIdentity(manifest: XenoHostedEnvironmentManifest): string;
+declare function deriveHostedIdempotencyKey(...parts: string[]): string;
+type XenoHostedWebhookSource = "github" | "gitlab" | "slack" | "teams" | "linear" | "jira" | "xeno";
+interface VerifyXenoHostedWebhookOptions {
+    source: XenoHostedWebhookSource;
+    body: Uint8Array | string;
+    secret: string;
+    signature?: string;
+    timestamp?: string;
+    now?: Date;
+    maxClockSkewMs?: number;
+}
+declare function verifyXenoHostedWebhook(options: VerifyXenoHostedWebhookOptions): XenoHostedWebhookVerification;
+declare const XENO_HOSTED_EXECUTION_ADAPTER_CERTIFICATION_SCHEMA: "xeno.hosted-execution-adapter-certification.v2";
+declare const XENO_HOSTED_EXECUTION_ADAPTER_PROTOCOL_VERSION: 2;
+declare const XENO_HOSTED_EXECUTION_ADAPTER_MAX_CERTIFICATE_LIFETIME_MS: number;
+interface XenoHostedExecutionAdapterCertification {
+    schemaVersion: typeof XENO_HOSTED_EXECUTION_ADAPTER_CERTIFICATION_SCHEMA;
+    certificationId: string;
+    adapter: {
+        name: string;
+        version: string;
+        protocolVersion: typeof XENO_HOSTED_EXECUTION_ADAPTER_PROTOCOL_VERSION;
+        executableSha256: string;
+    };
+    controlPlaneCandidateSha256: string;
+    platform: {
+        os: NodeJS.Platform;
+        architecture: NodeJS.Architecture;
+    };
+    capabilities: {
+        immutableImages: true;
+        filesystemIsolation: true;
+        networkDefaultDeny: true;
+        destinationAllowlist: true;
+        secretProjection: true;
+        nonRootExecution: true;
+        readOnlyRoot: true;
+        processTreeCleanup: true;
+        resourceLimits: true;
+        interactiveControl: true;
+        artifactProtocol: true;
+        gitResultReporting: true;
+    };
+    issuedAt: string;
+    expiresAt: string;
+    reviewer: {
+        keyId: string;
+    };
+    signature: {
+        algorithm: "ed25519";
+        value: string;
+    };
+}
+interface XenoHostedExecutionAdapterVerificationOptions {
+    executableSha256: string;
+    controlPlaneCandidateSha256: string;
+    trustedKeys: Record<string, string>;
+    now?: Date;
+    platform?: NodeJS.Platform;
+    architecture?: NodeJS.Architecture;
+}
+interface XenoVerifiedHostedExecutionAdapterCertification {
+    certificationId: string;
+    adapterName: string;
+    adapterVersion: string;
+    protocolVersion: typeof XENO_HOSTED_EXECUTION_ADAPTER_PROTOCOL_VERSION;
+    executableSha256: string;
+    controlPlaneCandidateSha256: string;
+    certificateSha256: string;
+    expiresAt: string;
+    reviewerKeyId: string;
+}
+declare function xenoHostedExecutionAdapterSigningPayload(certificate: Omit<XenoHostedExecutionAdapterCertification, "signature">): Buffer;
+declare function verifyXenoHostedExecutionAdapterCertification(certificate: XenoHostedExecutionAdapterCertification, options: XenoHostedExecutionAdapterVerificationOptions): XenoVerifiedHostedExecutionAdapterCertification;
+declare const XENO_HOSTED_EXECUTION_PROTOCOL_VERSION: 2;
+declare const XENO_HOSTED_EXECUTION_TOOL_NAMES: readonly [
+    "Read",
+    "Write",
+    "Edit",
+    "Glob",
+    "Grep",
+    "WebFetch"
+];
+interface XenoHostedExecutionSecretValue {
+    ref: string;
+    target: XenoHostedSecretProjection["target"];
+    exposeToChildProcesses: boolean;
+    value: string;
+}
+interface XenoHostedExecutionBoundaryReceipt {
+    certificationId: string;
+    environmentChecksum: string;
+    imageDigest: string;
+    networkPolicySha256: string;
+    secretProjectionSha256: string;
+    filesystem: "read" | "workspace-write";
+    network: "deny" | "allowlist";
+    immutableImage: true;
+    readOnlyRoot: true;
+    nonRoot: true;
+    processTreeCleanup: true;
+    resourceLimits: true;
+    inferenceGateway: "brokered";
+}
+interface XenoHostedExecutionJob {
+    protocolVersion: typeof XENO_HOSTED_EXECUTION_PROTOCOL_VERSION;
+    kind: "xeno-hosted-execution-job";
+    runId: string;
+    userId: string;
+    workspaceId: string;
+    workspaceHostPath: string;
+    prompt: string;
+    model: string;
+    effort?: string;
+    permissionMode: string;
+    runScopedToken: string;
+    inferenceBaseUrl: string;
+    allowedTools: readonly string[];
+    environment: XenoHostedEnvironmentManifest;
+    authority: XenoHostedAuthority;
+    budget: XenoHostedBudget;
+    secrets: XenoHostedExecutionSecretValue[];
+    expectedBoundary: XenoHostedExecutionBoundaryReceipt;
+}
+declare function createXenoHostedExecutionBoundaryReceipt(options: {
+    certificationId: string;
+    environment: XenoHostedEnvironmentManifest;
+    authority: XenoHostedAuthority;
+}): XenoHostedExecutionBoundaryReceipt;
+declare function verifyXenoHostedExecutionJob(value: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+declare function assertValidXenoHostedExecutionJob(value: unknown): asserts value is XenoHostedExecutionJob;
+declare const XENO_HOSTED_CONTROL_SCHEMA_VERSION: 1;
+declare const XENO_HOSTED_RESULT_SCHEMA_VERSION: 1;
+type XenoHostedControlAction = {
+    type: "message";
+    message: string;
+} | {
+    type: "approval";
+    requestId: string;
+    decision: "approved" | "rejected";
+    scopeHash: string;
+    rationale?: string;
+};
+interface XenoHostedControlCommandPayload {
+    schemaVersion: typeof XENO_HOSTED_CONTROL_SCHEMA_VERSION;
+    kind: "xeno-hosted-control";
+    controlId: string;
+    runId: string;
+    workspaceId: string;
+    actorId: string;
+    idempotencyKey: string;
+    createdAt: string;
+    action: XenoHostedControlAction;
+}
+interface XenoHostedControlCommand extends XenoHostedControlCommandPayload {
+    hash: {
+        algorithm: "sha256";
+        value: string;
+    };
+}
+interface XenoHostedControlAcknowledgement {
+    controlId: string;
+    status: "accepted" | "applied" | "rejected" | "unsupported";
+    acknowledgedAt: string;
+    reason?: string;
+}
+interface XenoHostedRunResultPayload {
+    schemaVersion: typeof XENO_HOSTED_RESULT_SCHEMA_VERSION;
+    kind: "xeno-hosted-run-result";
+    runId: string;
+    workspaceId: string;
+    completedAt: string;
+    git?: {
+        branch?: string;
+        baseRef?: string;
+        commit?: string;
+    };
+    pullRequest?: {
+        provider: string;
+        repository: string;
+        number: number;
+        url: string;
+    };
+    artifactIds: string[];
+    evidenceArtifactIds: string[];
+}
+interface XenoHostedRunResult extends XenoHostedRunResultPayload {
+    hash: {
+        algorithm: "sha256";
+        value: string;
+    };
+}
+declare function createXenoHostedControlCommand(payload: Omit<XenoHostedControlCommandPayload, "schemaVersion" | "kind" | "controlId"> & {
+    controlId?: string;
+}): XenoHostedControlCommand;
+declare function verifyXenoHostedControlCommand(command: XenoHostedControlCommand): {
+    valid: boolean;
+    errors: string[];
+};
+declare function normalizeXenoHostedControlAcknowledgement(value: XenoHostedControlAcknowledgement): XenoHostedControlAcknowledgement;
+declare function createXenoHostedRunResult(payload: Omit<XenoHostedRunResultPayload, "schemaVersion" | "kind">): XenoHostedRunResult;
+declare function verifyXenoHostedRunResult(result: XenoHostedRunResult): {
+    valid: boolean;
+    errors: string[];
+};
+export { type VerifyXenoHostedWebhookOptions, XENO_HOSTED_CONTROL_SCHEMA_VERSION, XENO_HOSTED_ENVIRONMENT_SCHEMA_VERSION, XENO_HOSTED_EVENT_SCHEMA_VERSION, XENO_HOSTED_EXECUTION_ADAPTER_CERTIFICATION_SCHEMA, XENO_HOSTED_EXECUTION_ADAPTER_MAX_CERTIFICATE_LIFETIME_MS, XENO_HOSTED_EXECUTION_ADAPTER_PROTOCOL_VERSION, XENO_HOSTED_EXECUTION_PROTOCOL_VERSION, XENO_HOSTED_EXECUTION_TOOL_NAMES, XENO_HOSTED_RESULT_SCHEMA_VERSION, XENO_HOSTED_RUN_SCHEMA_VERSION, XENO_HOSTED_TRIGGER_SCHEMA_VERSION, type XenoHostedArchitecture, type XenoHostedAuthority, type XenoHostedBudget, type XenoHostedCacheMount, type XenoHostedControlAcknowledgement, type XenoHostedControlAction, type XenoHostedControlCommand, type XenoHostedControlCommandPayload, type XenoHostedEnvironmentManifest, type XenoHostedEnvironmentManifestPayload, type XenoHostedEventRecord, type XenoHostedExecutionAdapterCertification, type XenoHostedExecutionAdapterVerificationOptions, type XenoHostedExecutionBoundaryReceipt, type XenoHostedExecutionJob, type XenoHostedExecutionSecretValue, type XenoHostedImageReference, type XenoHostedNetworkDestination, type XenoHostedNetworkPolicy, type XenoHostedOs, type XenoHostedQuotaLease, type XenoHostedReplayCursor, type XenoHostedReplayPage, type XenoHostedRepositorySource, type XenoHostedResourceLimits, type XenoHostedRetentionPolicy, type XenoHostedRunRecord, type XenoHostedRunRequest, type XenoHostedRunResult, type XenoHostedRunResultPayload, type XenoHostedRunStatus, type XenoHostedSecretProjection, type XenoHostedSetupStep, type XenoHostedTriggerDefinition, type XenoHostedTriggerDelivery, type XenoHostedTriggerKind, type XenoHostedWebhookSource, type XenoHostedWebhookVerification, type XenoVerifiedHostedExecutionAdapterCertification, assertValidXenoHostedExecutionJob, createXenoHostedControlCommand, createXenoHostedEnvironmentManifest, createXenoHostedEvent, createXenoHostedExecutionBoundaryReceipt, createXenoHostedRunResult, deriveHostedIdempotencyKey, hostedEnvironmentIdentity, normalizeXenoHostedControlAcknowledgement, verifyXenoHostedControlCommand, verifyXenoHostedEnvironmentManifest, verifyXenoHostedEventChain, verifyXenoHostedExecutionAdapterCertification, verifyXenoHostedExecutionJob, verifyXenoHostedRunResult, verifyXenoHostedWebhook, xenoHostedExecutionAdapterSigningPayload };