@kvell007/embed-labs-protocol 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,81 @@
+# @embed-labs/protocol
+
+Shared TypeScript contracts for Embed Labs Cloud clients, services, the CLI,
+and the local bridge.
+
+## Package Status
+
+This package is a publish candidate, but it is not ready for public npm publish
+yet. The workspace manifest intentionally remains marked `private: true` until
+package names, license, npm scope ownership, support URLs, and release approval
+are complete.
+
+## What It Provides
+
+- API success and failure envelopes.
+- Cloud task, project, event, artifact, and validation evidence contracts.
+- Server build template, workspace, resource lease, and execution mode
+  contracts.
+- Local bridge device, serial, probe, job, approval, and flash plan contracts.
+- Board Pack manifest and validation matrix types.
+- Small `ok()` and `fail()` helpers for consistent API responses.
+
+The package is types-first and has no direct hardware, network, filesystem, or
+process side effects.
+
+## Install
+
+After the package is approved for public release:
+
+```bash
+npm install @embed-labs/protocol
+```
+
+Internal workspace packages consume it through the monorepo dependency graph.
+
+## Usage
+
+```ts
+import {
+  fail,
+  ok,
+  type DeviceScanResult,
+  type FlashPlan,
+  type TaskStatus
+} from "@embed-labs/protocol";
+
+export function health() {
+  return ok({ service: "example", status: "ok" });
+}
+
+export function missingTask(taskId: string) {
+  return fail("task_not_found", `No task found for ${taskId}.`, {
+    retryable: false
+  });
+}
+```
+
+## Hardware Support Boundary
+
+This package only defines data contracts. Board identifiers, flash plan fields,
+and validation matrix types are not hardware support claims by themselves.
+Hardware detection, probing, and guarded flash behavior live in
+`@embed-labs/local-bridge`.
+
+Destructive TaishanPi flashing is not enabled by these contracts. The current
+local bridge can produce guarded planning evidence, but real TaishanPi flashing
+remains blocked until the relevant hardware profile and Board Pack command
+templates are accepted.
+
+## Runtime Requirements
+
+- Node.js 20 or newer for packages that execute the compiled ESM output.
+- TypeScript consumers should import the exported types from the package root.
+
+## Publish Readiness
+
+Before public publish, confirm the runbook checklist in
+`docs/runbooks/CLI_NPM_PACKAGING.md`, including approved SPDX license metadata,
+repository, issue tracker, homepage, support metadata, changelog or release
+notes, final npm scope ownership, and removal of `private: true` only in an
+approved metadata task.

package/dist/index.d.ts

@@ -0,0 +1,1227 @@
+export type TaskState = "created" | "queued" | "planning" | "awaiting_approval" | "running" | "blocked" | "cancel_requested" | "succeeded" | "failed" | "cancelled" | "expired";
+export type Severity = "info" | "warning" | "error";
+export interface ErrorEnvelope {
+    code: string;
+    message: string;
+    retryable?: boolean;
+    remediation?: string;
+    details?: Record<string, unknown>;
+}
+export interface ApiSuccess<T> {
+    ok: true;
+    data: T;
+}
+export interface ApiFailure {
+    ok: false;
+    error: ErrorEnvelope;
+}
+export type ApiResponse<T> = ApiSuccess<T> | ApiFailure;
+export interface TaskEvent {
+    event_id: string;
+    task_id: string;
+    type: string;
+    stage?: string;
+    message?: string;
+    severity?: Severity;
+    created_at: string;
+    data?: Record<string, unknown>;
+}
+export interface ArtifactMetadata {
+    artifact_id: string;
+    task_id?: string;
+    account_id?: string;
+    project_id?: string;
+    kind: "firmware" | "image" | "patch" | "log" | "manifest" | "screenshot" | "evidence" | "report" | "other";
+    name: string;
+    content_type?: string;
+    size_bytes?: number;
+    sha256?: string;
+    path?: string;
+    producer: "cloud" | "local_bridge" | "board" | "user";
+    created_at: string;
+}
+export interface ArtifactDownloadResult {
+    artifact_id: string;
+    output_path: string;
+    size_bytes: number;
+}
+export interface BoardDeployRequest {
+    board_id: "taishanpi" | (string & {});
+    host: string;
+    user?: string;
+    artifact_path: string;
+    remote_path?: string;
+    run?: boolean;
+    timeout_seconds?: number;
+    approved?: boolean;
+}
+export interface BoardDeployResult {
+    board_id: string;
+    host: string;
+    user: string;
+    artifact_path: string;
+    artifact_size_bytes?: number;
+    remote_path: string;
+    deployed: boolean;
+    ran: boolean;
+    remote_pid?: string;
+    log_path?: string;
+    exit_code?: number | null;
+    stdout?: string;
+    stderr?: string;
+    output_tail?: string[];
+    observed_at: string;
+}
+export type TaishanPiDeployRequest = BoardDeployRequest;
+export type TaishanPiDeployResult = BoardDeployResult;
+export interface ValidationEvidence {
+    evidence_id: string;
+    task_id?: string;
+    board_id?: string;
+    variant_id?: string;
+    hardware_profile_id?: string;
+    method: "build_log" | "flash_plan" | "serial_log" | "ssh_probe" | "screenshot" | "hash_check" | "test_report" | "probe";
+    summary: string;
+    observed_at: string;
+    artifact_ids?: string[];
+    verdict: "pass" | "fail" | "inconclusive";
+}
+export interface TaskStatus {
+    task_id: string;
+    state: TaskState;
+    kind: string;
+    account_id?: string;
+    project_id?: string;
+    workspace_id?: string;
+    progress_stage?: string;
+    progress_text?: string;
+    progress_percent?: number;
+    output_tail?: string[];
+    artifacts?: ArtifactMetadata[];
+    evidence?: ValidationEvidence[];
+    error?: ErrorEnvelope;
+    created_at: string;
+    updated_at: string;
+}
+export interface ProjectStatus {
+    project_id: string;
+    name: string;
+    board_id?: string;
+    workspace_path?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ProjectCreateRequest {
+    name: string;
+    board_id?: string;
+    workspace_path?: string;
+}
+export interface AccountStatus {
+    account_id: string;
+    email: string;
+    display_name?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AccountCreateRequest {
+    email: string;
+    display_name?: string;
+}
+export type AuthContextInfo = {
+    kind: "admin";
+} | {
+    kind: "api_key";
+    account_id: string;
+    api_key_id: string;
+};
+export interface ApiKeySummary {
+    api_key_id: string;
+    account_id: string;
+    name?: string;
+    key_prefix: string;
+    created_at: string;
+    last_used_at?: string;
+    revoked_at?: string;
+}
+export interface ApiKeyCreateRequest {
+    name?: string;
+}
+export interface ApiKeyCreateResult {
+    api_key: string;
+    api_key_record: ApiKeySummary;
+}
+export interface TokenUsageRecord {
+    usage_id: string;
+    account_id: string;
+    api_key_id: string;
+    provider?: string;
+    model: string;
+    operation?: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    task_id?: string;
+    request_id?: string;
+    created_at: string;
+}
+export interface TokenUsageCreateRequest {
+    api_key?: string;
+    api_key_id?: string;
+    provider?: string;
+    model: string;
+    operation?: string;
+    input_tokens: number;
+    output_tokens: number;
+    task_id?: string;
+    request_id?: string;
+    created_at?: string;
+}
+export interface TokenUsageModelSummary {
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    event_count: number;
+}
+export interface TokenUsageSummary {
+    account_id?: string;
+    api_key_id?: string;
+    from?: string;
+    to?: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    event_count: number;
+    by_model: TokenUsageModelSummary[];
+}
+export interface TokenUsageEventList {
+    account_id: string;
+    api_key_id?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    usage_events: TokenUsageRecord[];
+}
+export interface BillingStatementLine {
+    provider?: string;
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    event_count: number;
+    input_cost_microusd: number;
+    output_cost_microusd: number;
+    total_cost_microusd: number;
+}
+export interface BillingStatement {
+    account_id: string;
+    from?: string;
+    to?: string;
+    currency: "USD";
+    rate_source: "env";
+    input_microusd_per_token: number;
+    output_microusd_per_token: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    event_count: number;
+    input_cost_microusd: number;
+    output_cost_microusd: number;
+    total_cost_microusd: number;
+    line_items: BillingStatementLine[];
+    generated_at: string;
+}
+export interface BillingSnapshot {
+    billing_snapshot_id: string;
+    account_id: string;
+    from?: string;
+    to?: string;
+    currency: "USD";
+    rate_source: "env";
+    input_microusd_per_token: number;
+    output_microusd_per_token: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    event_count: number;
+    input_cost_microusd: number;
+    output_cost_microusd: number;
+    total_cost_microusd: number;
+    line_items: BillingStatementLine[];
+    statement_generated_at: string;
+    created_at: string;
+}
+export type BillingPaymentProvider = "mock" | "stripe" | "onchain";
+export type BillingRechargeSessionStatus = "pending" | "confirming" | "paid" | "expired" | "cancelled" | "manual_review";
+export interface AccountCreditBalance {
+    account_id: string;
+    currency: "USD";
+    balance_cents: number;
+    pending_recharge_cents: number;
+    updated_at: string;
+    source: "local";
+}
+export type TokenLedgerEntryKind = "recharge_credit" | "model_usage_debit" | "storage_debit";
+export interface AccountTokenBalance {
+    account_id: string;
+    balance_tokens: number;
+    updated_at: string;
+    source: "local";
+}
+export interface TokenLedgerEntry {
+    ledger_entry_id: string;
+    account_id: string;
+    kind: TokenLedgerEntryKind;
+    token_delta: number;
+    balance_after_tokens: number;
+    created_at: string;
+    idempotency_key: string;
+    usage_id?: string;
+    api_key_id?: string;
+    provider?: string;
+    model?: string;
+    task_id?: string;
+    workspace_id?: string;
+    metered_from?: string;
+    metered_to?: string;
+    description?: string;
+}
+export interface TokenLedgerEntryList {
+    entries: TokenLedgerEntry[];
+}
+export interface WorkspaceStorageUsage {
+    workspace_id: string;
+    account_id: string;
+    project_id: string;
+    template_id: string;
+    quota_mb: number;
+    allocated_bytes: number;
+    used_bytes: number;
+    age_seconds: number;
+    storage_token_rate_per_gb_hour: number;
+    accrued_storage_tokens: number;
+    created_at: string;
+    updated_at: string;
+    last_storage_settled_at?: string;
+    observed_at: string;
+}
+export interface AccountStorageSummary {
+    account_id: string;
+    quota_mb: number;
+    allocated_mb: number;
+    allocated_bytes: number;
+    used_bytes: number;
+    workspace_count: number;
+    storage_token_rate_per_gb_hour: number;
+    accrued_storage_tokens: number;
+    observed_at: string;
+    workspaces: WorkspaceStorageUsage[];
+}
+export interface StorageSettlementRequest {
+    dry_run?: boolean;
+}
+export interface StorageSettlementWorkspaceLine {
+    workspace_id: string;
+    project_id: string;
+    template_id: string;
+    quota_mb: number;
+    metered_from: string;
+    metered_to: string;
+    duration_seconds: number;
+    storage_token_rate_per_gb_hour: number;
+    tokens: number;
+}
+export interface StorageSettlementResult {
+    account_id: string;
+    dry_run: boolean;
+    settled_at: string;
+    balance_before_tokens: number;
+    balance_after_tokens: number;
+    tokens_debited: number;
+    ledger_entries: TokenLedgerEntry[];
+    workspaces: StorageSettlementWorkspaceLine[];
+}
+export interface BillingRechargeSessionCreateRequest {
+    account_id?: string;
+    amount_cents?: number;
+    amount_usd?: string | number;
+    currency?: "USD";
+    provider?: BillingPaymentProvider;
+    chain?: string;
+    token_symbol?: string;
+    success_url?: string;
+    cancel_url?: string;
+}
+export interface BillingOnchainPaymentDetails {
+    chain: string;
+    chain_id?: string;
+    token_symbol: string;
+    token_contract?: string;
+    token_decimals: number;
+    token_amount: string;
+    token_amount_units: string;
+    receive_address: string;
+    payment_uri: string;
+    required_confirmations: number;
+    tx_hash?: string;
+    received_at?: string;
+    confirmed_at?: string;
+    explorer_url?: string;
+}
+export interface BillingRechargeSessionTxSubmitRequest {
+    tx_hash?: string;
+    transaction_hash?: string;
+}
+export interface BillingRechargeSession {
+    recharge_session_id: string;
+    account_id: string;
+    provider: BillingPaymentProvider;
+    amount_cents: number;
+    currency: "USD";
+    status: BillingRechargeSessionStatus;
+    checkout_url: string;
+    qr_payload: string;
+    supported_payment_method_policy: "provider_dynamic" | "onchain_wallet_only";
+    provider_session_id?: string;
+    onchain?: BillingOnchainPaymentDetails;
+    created_at: string;
+    expires_at: string;
+    paid_at?: string;
+}
+export interface BillingRechargeSessionList {
+    recharge_sessions: BillingRechargeSession[];
+}
+export interface BuildTemplateWorkspace {
+    root_kind: string;
+    seed_relative_path: string;
+    user_workspace_relative_path: string;
+    artifact_relative_path: string;
+    cache_relative_path: string;
+    copy_strategy: string;
+    ignored_names?: string[];
+}
+export interface BuildTemplateDockerMount {
+    name: string;
+    container_path: string;
+    mode: "ro" | "rw" | string;
+}
+export interface BuildTemplateDocker {
+    image: string;
+    dockerfile: string;
+    workdir: string;
+    network: string;
+    run_as: string;
+    mounts: BuildTemplateDockerMount[];
+}
+export interface BuildTemplateResourceLimits {
+    cpu: number;
+    memory_mb: number;
+    timeout_seconds: number;
+    disk_mb: number;
+}
+export interface BuildTemplateValidation {
+    support_level_after_template_validation: string;
+    required_before_l1: string[];
+    required_before_l3: string[];
+}
+export interface BuildTemplate {
+    schema_version: string;
+    template_id: string;
+    display_name: string;
+    board_id: string;
+    variant_id: string;
+    hardware_profile_id: string;
+    default_build_profile_id: string;
+    image_build_profile_id?: string;
+    workspace: BuildTemplateWorkspace;
+    docker: BuildTemplateDocker;
+    resource_limits: BuildTemplateResourceLimits;
+    outputs: string[];
+    validation: BuildTemplateValidation;
+}
+export interface BuildTemplateList {
+    templates: BuildTemplate[];
+}
+export type BoardKnowledgeSource = "board_pack" | "build_template" | "registry";
+export interface BoardKnowledgeFileSummary {
+    source: BoardKnowledgeSource;
+    path: string;
+    title: string;
+    kind: "markdown" | "json" | "text" | "other";
+    content_type: string;
+    size_bytes: number;
+    sha256: string;
+}
+export interface BoardKnowledgeFile {
+    template_id: string;
+    board_id: string;
+    variant_id: string;
+    file: BoardKnowledgeFileSummary;
+    encoding: "base64";
+    content_base64: string;
+    observed_at: string;
+}
+export type BoardServerMethodOperation = "workspace.provision" | "source.list" | "source.read" | "source.write" | "app.build" | "app.compile" | "image.build" | "artifact.download" | "workspace.release";
+export interface BoardServerMethodSummary {
+    method_id: string;
+    operation: BoardServerMethodOperation;
+    display_name: string;
+    description: string;
+    runtime: "cloud_api" | "scheduler_worker" | "local_bridge";
+    http_method: "GET" | "POST";
+    path: string;
+    requires_workspace: boolean;
+    destructive: boolean;
+    requires_approval: boolean;
+    status: "available" | "mvp_stub" | "mvp_direct" | "planned";
+    input_schema: Record<string, unknown>;
+    output_artifact_kinds?: ArtifactMetadata["kind"][];
+    notes?: string[];
+}
+export interface BoardServerProfile {
+    template_id: string;
+    board_id: string;
+    variant_id: string;
+    hardware_profile_id: string;
+    display_name: string;
+    support_level: string;
+    build_template: BuildTemplate;
+    knowledge_files: BoardKnowledgeFileSummary[];
+    methods: BoardServerMethodSummary[];
+    observed_at: string;
+}
+export interface BoardServerProfileList {
+    observed_at: string;
+    profiles: BoardServerProfile[];
+}
+export type BuildWorkspaceCopyMode = "auto" | "copy" | "symlink" | "skeleton";
+export interface BuildWorkspaceProvisionRequest {
+    account_id: string;
+    project_id: string;
+    template_id?: string;
+    copy_mode?: BuildWorkspaceCopyMode;
+    require_seed?: boolean;
+    dry_run?: boolean;
+}
+export interface BuildWorkspaceProvisionResult {
+    workspace_id?: string;
+    template_id: string;
+    board_id: string;
+    variant_id: string;
+    hardware_profile_id: string;
+    account_id: string;
+    project_id: string;
+    build_root: string;
+    workspace_path: string;
+    source_path: string;
+    artifact_path: string;
+    cache_path: string;
+    seed_path: string;
+    seed_found: boolean;
+    copy_mode: BuildWorkspaceCopyMode;
+    storage_quota_mb?: number;
+    dry_run: boolean;
+    commands: string[];
+    created_at?: string;
+    updated_at?: string;
+}
+export interface BuildWorkspaceRecord {
+    workspace_id: string;
+    template_id: string;
+    board_id: string;
+    variant_id: string;
+    hardware_profile_id: string;
+    account_id: string;
+    project_id: string;
+    build_root: string;
+    workspace_path: string;
+    source_path: string;
+    artifact_path: string;
+    cache_path: string;
+    seed_path: string;
+    seed_found: boolean;
+    copy_mode: BuildWorkspaceCopyMode;
+    storage_quota_mb: number;
+    created_at: string;
+    updated_at: string;
+    storage_settled_at?: string;
+    released_at?: string;
+}
+export interface BuildWorkspaceList {
+    workspaces: BuildWorkspaceRecord[];
+}
+export interface BuildWorkspaceReleaseRequest {
+    dry_run?: boolean;
+    settle_storage?: boolean;
+}
+export interface BuildWorkspaceReleaseResult {
+    workspace_id: string;
+    account_id: string;
+    project_id: string;
+    dry_run: boolean;
+    released_at?: string;
+    deleted_paths: string[];
+    storage_settlement?: StorageSettlementResult;
+}
+export interface BuildWorkspaceSourceFile {
+    path: string;
+    content_base64: string;
+    size_bytes?: number;
+    sha256?: string;
+}
+export interface BuildWorkspaceSourceSyncRequest {
+    account_id?: string;
+    files: BuildWorkspaceSourceFile[];
+}
+export interface BuildWorkspaceSourceSyncResult {
+    workspace_id: string;
+    source_path: string;
+    file_count: number;
+    total_bytes: number;
+    written_files: string[];
+    updated_at: string;
+}
+export interface BuildWorkspaceSourceListResult {
+    workspace_id: string;
+    source_path: string;
+    file_count: number;
+    files: Array<{
+        path: string;
+        size_bytes: number;
+        sha256: string;
+    }>;
+    updated_at: string;
+}
+export interface BuildWorkspaceSourceReadResult {
+    workspace_id: string;
+    source_path: string;
+    path: string;
+    content_base64: string;
+    size_bytes: number;
+    sha256: string;
+    updated_at: string;
+}
+export interface BuildWorkspaceSourceSearchRequest {
+    query: string;
+    glob?: string;
+    max_results?: number;
+}
+export interface BuildWorkspaceSourceSearchMatch {
+    path: string;
+    line: number;
+    column: number;
+    line_text: string;
+    context_before: string[];
+    context_after: string[];
+    size_bytes: number;
+    sha256: string;
+}
+export interface BuildWorkspaceSourceSearchResult {
+    workspace_id: string;
+    source_path: string;
+    query: string;
+    glob?: string;
+    max_results: number;
+    result_count: number;
+    truncated: boolean;
+    scanned_files: number;
+    skipped_files: number;
+    matches: BuildWorkspaceSourceSearchMatch[];
+    updated_at: string;
+}
+export interface BuildWorkspaceSourcePatchFile {
+    path: string;
+    content_base64?: string;
+    delete?: boolean;
+    size_bytes?: number;
+    sha256?: string;
+}
+export interface BuildWorkspaceSourcePatchRequest {
+    account_id?: string;
+    patch?: string;
+    files?: BuildWorkspaceSourcePatchFile[];
+}
+export interface BuildWorkspaceSourcePatchedFile {
+    path: string;
+    operation: "created" | "updated" | "deleted";
+    size_bytes?: number;
+    sha256?: string;
+}
+export interface BuildWorkspaceSourcePatchResult {
+    workspace_id: string;
+    source_path: string;
+    file_count: number;
+    modified_files: BuildWorkspaceSourcePatchedFile[];
+    updated_at: string;
+}
+export type BuildExecutionMode = "cloud_worker" | "local_bridge" | "dry_run";
+export type BuildResourceLeaseStatus = "active" | "released" | "expired";
+export interface BuildResourceLeaseRequest {
+    workspace_id: string;
+    account_id?: string;
+    task_id?: string;
+    execution_mode?: BuildExecutionMode;
+    ttl_seconds?: number;
+    worker_pool?: string;
+    purpose?: string;
+}
+export interface BuildResourceLeaseIsolation {
+    workspace_path: string;
+    source_path: string;
+    artifact_path: string;
+    cache_path: string;
+    docker_image: string;
+    docker_workdir: string;
+    docker_network: string;
+    docker_run_as: string;
+    mounts: BuildTemplateDockerMount[];
+    resource_limits: BuildTemplateResourceLimits;
+}
+export interface BuildResourceLeaseRecord {
+    lease_id: string;
+    status: BuildResourceLeaseStatus;
+    execution_mode: BuildExecutionMode;
+    account_id: string;
+    project_id: string;
+    workspace_id: string;
+    template_id: string;
+    task_id?: string;
+    worker_pool?: string;
+    purpose?: string;
+    isolation: BuildResourceLeaseIsolation;
+    created_at: string;
+    expires_at: string;
+    released_at?: string;
+}
+export interface BuildResourceLeaseReleaseRequest {
+    reason?: string;
+}
+export interface BuildApplicationStubRequest {
+    workspace_id: string;
+    account_id?: string;
+}
+export type BuildApplicationCompileMode = "server_direct" | "docker_worker" | "dry_run";
+export type BuildApplicationCompiler = "auto" | "cc" | "gcc" | "clang" | "aarch64-linux-gnu-gcc";
+export interface BuildApplicationCompileRequest {
+    workspace_id: string;
+    account_id?: string;
+    source_path?: string;
+    output_name?: string;
+    execution_mode?: BuildApplicationCompileMode;
+    compiler?: BuildApplicationCompiler;
+}
+export type AgentProvider = "stub" | "openai" | "bai" | "claude-code";
+export type AgentProviderInput = AgentProvider | "b.ai" | "cc";
+export type ModelProviderStatus = "available" | "configured" | "not_configured" | "not_implemented";
+export interface ModelProviderSummary {
+    provider: AgentProvider;
+    display_name: string;
+    model: string;
+    status: ModelProviderStatus;
+    default: boolean;
+    supports_tools: boolean;
+    supports_streaming: boolean;
+    notes?: string[];
+}
+export interface ModelCatalog {
+    default_provider: AgentProvider;
+    default_model: string;
+    models: ModelProviderSummary[];
+    observed_at: string;
+}
+export interface ModelDefault {
+    provider: AgentProvider;
+    model: string;
+    status: ModelProviderStatus;
+    observed_at: string;
+}
+export type ServiceModeId = "managed-model-token" | "bring-your-own-model" | "resource-only";
+export type ServiceModeStatus = "available" | "not_configured" | "planned";
+export type ServiceModeModelTokenSource = "embed_labs" | "user" | "none";
+export type ServiceModeMeter = "managed_model_tokens" | "workspace_storage_tokens" | "build_compute_tokens" | "artifact_storage_tokens" | "subscription";
+export interface ServiceModeSummary {
+    mode: ServiceModeId;
+    display_name: string;
+    status: ServiceModeStatus;
+    default: boolean;
+    model_token_source: ServiceModeModelTokenSource;
+    includes_model_gateway: boolean;
+    includes_server_build_resources: boolean;
+    supports_external_cli_agents: boolean;
+    meters: ServiceModeMeter[];
+    notes?: string[];
+}
+export interface ServiceModeCatalog {
+    default_mode: ServiceModeId;
+    observed_at: string;
+    modes: ServiceModeSummary[];
+    boundaries: {
+        model_gateway: string;
+        server_resource_orchestration: string;
+        local_bridge: string;
+    };
+}
+export interface BuildApplicationGenerateRequest {
+    workspace_id: string;
+    account_id?: string;
+    prompt: string;
+    target_path?: string;
+    provider?: AgentProviderInput;
+    model?: string;
+}
+export interface BuildImageGenerateRequest {
+    workspace_id: string;
+    account_id?: string;
+    prompt: string;
+    image_profile_id?: string;
+    provider?: AgentProviderInput;
+    model?: string;
+    execution_mode?: BuildExecutionMode;
+    worker_pool?: string;
+}
+export interface AgentTaskCreateRequest {
+    prompt: string;
+    project_id?: string;
+    board_id?: string;
+    kind?: string;
+}
+export interface DeviceLocator {
+    transport: "usb" | "serial" | "ssh" | "usbecm" | "uf2-volume" | "rockusb" | "unknown";
+    path?: string;
+    host?: string;
+    port?: number;
+    interface_name?: string;
+    volume_path?: string;
+}
+export interface UsbDeviceInfo {
+    vendor_id?: string;
+    product_id?: string;
+    vendor_name?: string;
+    product_name?: string;
+    serial_number?: string;
+    location_id?: string;
+    raw?: Record<string, unknown>;
+}
+export interface SerialPortInfo {
+    path: string;
+    display_name?: string;
+    vendor_id?: string;
+    product_id?: string;
+    serial_number?: string;
+    available: boolean;
+}
+export interface DeviceSummary {
+    device_id: string;
+    board_id?: string;
+    variant_id?: string;
+    hardware_profile_id?: string;
+    display_name: string;
+    status: "connected" | "disconnected" | "bootloader" | "unknown" | "not_ready";
+    locators: DeviceLocator[];
+    usb?: UsbDeviceInfo;
+    serial?: SerialPortInfo;
+    observed_at: string;
+    summary_for_user: string;
+    evidence?: ValidationEvidence[];
+}
+export interface DeviceScanResult {
+    devices: DeviceSummary[];
+    usb: UsbDeviceInfo[];
+    serial: SerialPortInfo[];
+    observed_at: string;
+    warnings?: ErrorEnvelope[];
+}
+export interface DeviceProbeRequest {
+    host?: string;
+    ports?: number[];
+    serial_paths?: string[];
+    timeout_ms?: number;
+}
+export interface TcpProbeEvidence {
+    transport: "tcp";
+    host: string;
+    port: number;
+    reachable: boolean;
+    duration_ms: number;
+    observed_at: string;
+    error_code?: string;
+    error_message?: string;
+}
+export interface SerialPathProbeEvidence {
+    transport: "serial-path";
+    path: string;
+    exists: boolean;
+    path_type: "character_device" | "file" | "directory" | "other" | "unknown";
+    readable?: boolean;
+    writable?: boolean;
+    observed_at: string;
+    error_code?: string;
+    error_message?: string;
+}
+export interface DeviceProbeResult {
+    observed_at: string;
+    timeout_ms: number;
+    tcp: TcpProbeEvidence[];
+    serial_paths: SerialPathProbeEvidence[];
+    summary_for_user: string;
+    warnings?: ErrorEnvelope[];
+}
+export type DebugToolId = "openocd" | "probe-rs" | "pyocd" | "jlink-commander" | "jlink-gdb-server" | (string & {});
+export type DebugToolEvidenceKind = "path_lookup" | "version_command";
+export interface DebugToolEvidence {
+    evidence_id: string;
+    tool_id: DebugToolId;
+    kind: DebugToolEvidenceKind;
+    command: string;
+    args?: string[];
+    observed_at: string;
+    available?: boolean;
+    resolved_path?: string;
+    exit_code?: number | null;
+    timed_out?: boolean;
+    stdout_tail?: string[];
+    stderr_tail?: string[];
+    error_code?: string;
+    error_message?: string;
+    summary: string;
+}
+export interface DebugToolSummary {
+    tool_id: DebugToolId;
+    display_name: string;
+    command: string;
+    available: boolean;
+    version?: string;
+    evidence: DebugToolEvidence[];
+    summary_for_user: string;
+}
+export interface DebugToolScanResult {
+    tools: DebugToolSummary[];
+    observed_at: string;
+    summary_for_user: string;
+    warnings?: ErrorEnvelope[];
+}
+export type ToolRuntime = "local_bridge" | "cloud" | "mcp" | "hosted";
+export type ToolCapabilityId = "debug.tools.scan" | "device.scan" | "device.probe" | "taishanpi.deploy" | (string & {});
+export interface ToolCapabilitySummary {
+    capability_id: ToolCapabilityId;
+    display_name: string;
+    description: string;
+    runtime: ToolRuntime;
+    category: string;
+    destructive: boolean;
+    requires_approval: boolean;
+    input_schema: Record<string, unknown>;
+}
+export interface ToolCapabilityList {
+    capabilities: ToolCapabilitySummary[];
+    observed_at: string;
+}
+export interface ToolInvokeRequest {
+    capability_id: ToolCapabilityId;
+    input?: Record<string, unknown>;
+    approved?: boolean;
+}
+export interface ToolInvokeResult {
+    capability_id: ToolCapabilityId;
+    result: unknown;
+    observed_at: string;
+}
+export interface AgentLocalToolRunRequest {
+    prompt: string;
+    account_id?: string;
+    workspace_id?: string;
+    provider?: AgentProviderInput;
+    model?: string;
+    max_tool_calls?: number;
+    tool_inputs?: Record<string, Record<string, unknown>>;
+    tools: ToolCapabilitySummary[];
+}
+export interface AgentLocalToolCall {
+    tool_call_id: string;
+    capability_id: ToolCapabilityId;
+    input: Record<string, unknown>;
+    requires_approval: boolean;
+    reason: string;
+}
+export interface AgentLocalToolPlan {
+    plan_id: string;
+    request_id: string;
+    account_id?: string;
+    workspace_id?: string;
+    provider: AgentProvider;
+    model: string;
+    prompt: string;
+    prompt_sha256: string;
+    assistant_message: string;
+    tool_calls: AgentLocalToolCall[];
+    created_at: string;
+    expires_at: string;
+}
+export interface AgentLocalToolResultItem {
+    tool_call_id: string;
+    capability_id: ToolCapabilityId;
+    ok: boolean;
+    output?: unknown;
+    error?: ErrorEnvelope;
+}
+export interface AgentLocalToolCompleteRequest {
+    plan_id: string;
+    prompt: string;
+    account_id?: string;
+    workspace_id?: string;
+    provider?: AgentProviderInput;
+    model?: string;
+    tool_results: AgentLocalToolResultItem[];
+}
+export interface AgentLocalToolCompleteResult {
+    plan_id: string;
+    request_id: string;
+    usage_id?: string;
+    provider: AgentProvider;
+    model: string;
+    answer: string;
+    tool_results: AgentLocalToolResultItem[];
+    input_tokens: number;
+    output_tokens: number;
+    created_at: string;
+}
+export type DoctorCheckStatus = "ready" | "not_ready" | "unreachable" | "warning";
+export type DoctorCheckId = "cli_runtime" | "auth" | "bridge_health" | "device_scan" | "debug_tools" | "cloud_api_health" | (string & {});
+export interface DoctorCheck<T = unknown> {
+    id: DoctorCheckId;
+    label: string;
+    status: DoctorCheckStatus;
+    summary: string;
+    observed_at: string;
+    target?: string;
+    duration_ms?: number;
+    http_status?: number;
+    data?: T;
+    error?: ErrorEnvelope;
+}
+export interface DoctorResult {
+    status: "ready" | "not_ready";
+    observed_at: string;
+    summary_for_user: string;
+    checks: DoctorCheck[];
+}
+export interface BridgeJob {
+    local_job_id: string;
+    state: TaskState;
+    kind: string;
+    progress_stage?: string;
+    progress_text?: string;
+    progress_percent?: number;
+    output_tail?: string[];
+    result?: Record<string, unknown>;
+    error?: ErrorEnvelope;
+    created_at: string;
+    updated_at: string;
+}
+export interface ApprovalRecord {
+    approval_id: string;
+    task_id?: string;
+    requested_action: string;
+    risk_level: "low" | "medium" | "high" | "destructive";
+    plan_summary: string;
+    affected_device_id?: string;
+    affected_artifacts?: string[];
+    expires_at?: string;
+    decision?: "approved" | "rejected" | "expired";
+    decided_by?: string;
+    decided_at?: string;
+}
+export interface FlashPartitionPlan {
+    partition: string;
+    image_path: string;
+    required: boolean;
+    size_bytes?: number;
+    sha256?: string;
+}
+export interface FlashPlan {
+    plan_id: string;
+    board_id: string;
+    variant_id?: string;
+    hardware_profile_id?: string;
+    profile_id: string;
+    destructive: boolean;
+    approval_required: boolean;
+    ready: boolean;
+    summary: string;
+    partitions?: FlashPartitionPlan[];
+    artifact_path?: string;
+    target_volume_path?: string;
+    required_tools?: string[];
+    missing_tools?: string[];
+    missing_files?: string[];
+    warnings?: ErrorEnvelope[];
+}
+export interface FlashPlanRequest {
+    board_id: string;
+    variant_id?: string;
+    hardware_profile_id?: string;
+    profile_id?: string;
+    image_dir?: string;
+    artifact_path?: string;
+    target_volume_path?: string;
+}
+export interface FlashRunRequest extends FlashPlanRequest {
+    approved: boolean;
+}
+export type BoardPackExecutionPlane = "cloud" | "local_bridge" | "board" | (string & {});
+export interface BoardPackVariant {
+    variant_id: string;
+    display_name: string;
+    hardware_profiles?: string[];
+    [key: string]: unknown;
+}
+export interface BoardPackProfileBase {
+    profile_id: string;
+    display_name?: string;
+    description?: string;
+    status?: string;
+    notes?: string;
+    [key: string]: unknown;
+}
+export interface BoardPackBuildProfile extends BoardPackProfileBase {
+    kind?: string;
+    execution_plane?: BoardPackExecutionPlane;
+    outputs?: string[];
+}
+export interface BoardPackFlashProfile extends BoardPackProfileBase {
+    execution_plane?: BoardPackExecutionPlane;
+    destructive?: boolean;
+    approval_required?: boolean;
+    required_files?: string[];
+    required_tools?: string[];
+    artifact_extensions?: string[];
+    target?: string;
+}
+export interface BoardPackDebugProfile extends BoardPackProfileBase {
+    execution_plane?: BoardPackExecutionPlane;
+    transports?: string[];
+}
+export interface BoardPackImageProfile extends BoardPackProfileBase {
+    required_outputs?: string[];
+}
+export type BoardPackValidationOperationMode = "planned" | "dry_run" | "executed" | "executed_non_destructive" | "executed_destructive" | "destructive" | (string & {});
+export type BoardPackValidationApprovalRequirement = boolean | "required_for_destructive_only" | "required_for_flash_or_image_deployment" | (string & {});
+export type BoardPackValidationDestructiveOperation = boolean | "mixed" | (string & {});
+export interface BoardPackValidationScopeVariant {
+    variant_id: string;
+    hardware_profiles?: string[];
+    [key: string]: unknown;
+}
+export interface BoardPackValidationScope {
+    board_id?: string;
+    variants?: BoardPackValidationScopeVariant[];
+    variant_ids?: string[];
+    hardware_profile_ids?: string[];
+    hardware_evidence_granularity?: string;
+    profile_ids?: string[];
+    capability_ids?: string[];
+    [key: string]: unknown;
+}
+export interface BoardPackValidationEvidenceClass {
+    id: BoardPackValidationOperationMode;
+    meaning: string;
+    [key: string]: unknown;
+}
+export interface BoardPackValidationEvidenceRequirement {
+    id?: string;
+    evidence_id?: string;
+    evidence_class?: BoardPackValidationOperationMode;
+    kind?: string;
+    summary?: string;
+    description?: string;
+    profile_id?: string;
+    profile_ids?: string[];
+    required?: boolean;
+    operation_modes?: BoardPackValidationOperationMode[];
+    fields?: string[];
+    artifact_kinds?: ArtifactMetadata["kind"][];
+    scope?: BoardPackValidationScope;
+    [key: string]: unknown;
+}
+export interface BoardPackValidationApprovalRule {
+    approval_required: boolean;
+    default_allowed?: boolean;
+    requirements?: string[];
+    [key: string]: unknown;
+}
+export interface BoardPackValidationApprovalPolicy {
+    [operation_mode: string]: BoardPackValidationApprovalRule;
+}
+export interface BoardPackValidationSupportClaimPolicy {
+    current_claim?: string;
+    higher_levels_not_claimed?: string[];
+    rule?: string;
+    evidence_storage?: string;
+    [key: string]: unknown;
+}
+export interface BoardPackValidationDestructiveOperationPolicy {
+    allowed: boolean;
+    approval_required?: boolean;
+    operation_modes?: BoardPackValidationOperationMode[];
+    summary?: string;
+    [key: string]: unknown;
+}
+export interface BoardPackValidationResidualRisk {
+    risk_id?: string;
+    summary: string;
+    severity?: Severity;
+    mitigation?: string;
+    [key: string]: unknown;
+}
+export interface BoardPackValidationGate {
+    gate_id: string;
+    display_name?: string;
+    support_level?: string;
+    applicable?: boolean;
+    claim_status?: string;
+    scope?: BoardPackValidationScope;
+    destructive_operation?: BoardPackValidationDestructiveOperation;
+    approval_required?: BoardPackValidationApprovalRequirement;
+    not_applicable_reason?: string;
+    required_evidence: BoardPackValidationEvidenceRequirement[];
+    destructive_operations?: BoardPackValidationDestructiveOperationPolicy;
+    residual_risks?: Array<string | BoardPackValidationResidualRisk>;
+    [key: string]: unknown;
+}
+export interface BoardPackValidationMatrix {
+    schema_version?: string;
+    board_id: string;
+    display_name?: string;
+    matrix_status?: string;
+    source_manifest?: string;
+    current_support_level?: string;
+    support_level?: string;
+    support_claim_policy?: BoardPackValidationSupportClaimPolicy;
+    validation_scope?: BoardPackValidationScope;
+    evidence_classes?: BoardPackValidationEvidenceClass[];
+    approval_policy?: BoardPackValidationApprovalPolicy;
+    gates: BoardPackValidationGate[];
+    task_evidence_fields?: string[];
+    required_task_evidence_fields?: string[];
+    guardrails?: string[];
+    residual_risks?: Array<string | BoardPackValidationResidualRisk>;
+    [key: string]: unknown;
+}
+export interface BoardPackManifest {
+    board_id: string;
+    display_name: string;
+    vendor: string;
+    family: string;
+    variants: BoardPackVariant[];
+    support_level: string;
+    capabilities: string[];
+    default_build_profile?: string;
+    default_flash_profile?: string;
+    default_debug_profile?: string;
+    build_profiles?: BoardPackBuildProfile[];
+    flash_profiles?: BoardPackFlashProfile[];
+    debug_profiles?: BoardPackDebugProfile[];
+    image_profiles?: BoardPackImageProfile[];
+}
+export declare function ok<T>(data: T): ApiSuccess<T>;
+export declare function fail(code: string, message: string, options?: Omit<ErrorEnvelope, "code" | "message">): ApiFailure;

package/dist/index.js

@@ -0,0 +1,7 @@
+export function ok(data) {
+    return { ok: true, data };
+}
+export function fail(code, message, options = {}) {
+    return { ok: false, error: { code, message, ...options } };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAu5CA,MAAM,UAAU,EAAE,CAAI,IAAO;IAC3B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAY,EAAE,OAAe,EAAE,UAAmD,EAAE;IACvG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,CAAC;AAC7D,CAAC"}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@kvell007/embed-labs-protocol",
+  "version": "0.1.0-alpha.0",
+  "description": "Shared TypeScript protocol contracts for Embed Labs Cloud. Experimental npm publish.",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}