@shardflux/sdk 0.5.0 → 0.6.0

package/dist/progress.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Lifecycle timing and progress. A slow open (0.8 s one day, 34 s the next) should say where the time went without a
+ * packet capture: waiting for a host, the cell booting or restoring the VM, the network between the caller and the API,
+ * the first tool token, or retries.
+ *
+ * A Trace follows one SDK call (open, a lifecycle call with `wait`, a wake, a token fetch). It records two clocks and
+ * never mixes them:
+ *
+ * - client phases, on the caller's monotonic clock: the request, then each operation state the SDK observed while
+ *   waiting (`queued`, `capacity_pending`, `running`, with the server's `state_reason`), then reading the view and
+ *   issuing the first token;
+ * - server timing, from the operation's own timestamps (one database clock: created_at, started_at, completed_at) and
+ *   what the cell reported in its result (start path, boot-to-ready, host restore steps).
+ *
+ * `outsideServerMs` is the difference: time the caller spent that the operation did not (network, TLS, client queues,
+ * polling latency, view and token). Listeners get the phases live; the finished call returns a LifecycleTiming.
+ */
+import type { components } from './generated/app-api.js';
+type Operation = components['schemas']['Operation'];
+/** The SDK call a trace follows. `wait` is a direct waitForOperation(); `token` a tool token fetched for tool calls. */
+export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork' | 'delete' | 'close' | 'reset' | 'wake' | 'wait' | 'token';
+/**
+ * - `request`: an API request that starts or joins the operation. A held open (`Prefer: wait`) spends the server's
+ *   hold here (reason `held`), so the states inside it show only in the server timing.
+ * - `queued`, `capacity_pending`, `running`: operation states as the SDK observed them while waiting, with the
+ *   operation's `state_reason` (e.g. `no_ready_host`, `template_downloading`).
+ * - `view`: reading the workspace after the operation. `token`: issuing a tool token (concurrent with `view` in open()).
+ * - `busy`: a tool call waiting out `workspace_busy` (only in `tool` events).
+ */
+export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy';
+export interface TimingPhase {
+    phase: LifecyclePhase;
+    /** The server's state_reason, or why the SDK entered the phase (`held`, `initial`, `expiring`, `invalidated`). */
+    reason: string | null;
+    operationId: string | null;
+    /** Milliseconds from the start of the call (client monotonic clock). */
+    startMs: number;
+    durationMs: number;
+}
+export interface RetryRecord {
+    atMs: number;
+    /** Method and path, e.g. `POST /v1/workspaces/open`. */
+    request: string;
+    /** 1 for the first retry. */
+    attempt: number;
+    /** `HTTP 503 unavailable`, `timeout after 30000 ms`, `network: ECONNRESET`, `conflict operation_in_progress`, `stale_epoch`. */
+    cause: string;
+    /** Backoff before the retry. */
+    delayMs: number;
+}
+/** The operation's own account (database clock and cell-reported results); independent of the caller's network. */
+export interface ServerTiming {
+    operationId: string;
+    kind: Operation['kind'];
+    state: Operation['state'];
+    /**
+     * created_at → started_at: waiting until the cell began running the operation, including any wait for a host with
+     * capacity (started_at is set when the operation first enters `running`). Null when the API does not report
+     * started_at or the operation has not run yet. An operation that finished without running (e.g. a failed dependency)
+     * has started_at = completed_at, so all of its time shows here.
+     */
+    queuedMs: number | null;
+    /** started_at → completed_at: the cell executing it (placement, boot or restore, guest readiness). Null until finished. */
+    runMs: number | null;
+    /** created_at → completed_at. Null until finished. */
+    totalMs: number | null;
+    /** `result.start_path`: `warm` (cloned from a warm snapshot) or `boot`. */
+    startPath: string | null;
+    /** `result.warm_fallback`: why a start that could be warm booted instead. */
+    warmFallback: string | null;
+    /** `result.resume_path`: `local_cache` or `download` (the checkpoint had to be fetched first). */
+    resumePath: string | null;
+    /** `result.boot_to_ready_ms`: VM start until the guest agent answered. */
+    bootToReadyMs: number | null;
+    /** `result.host_timings_ms`: the host's own steps (restore: load, after_restore, ready, …). */
+    hostTimingsMs: Record<string, number> | null;
+}
+export type TimingOutcome = 'succeeded' | 'failed' | 'timed_out' | 'error';
+export interface LifecycleTiming {
+    action: LifecycleAction;
+    outcome: TimingOutcome;
+    workspaceId: string | null;
+    operationId: string | null;
+    /** Wall time of the call on the caller's monotonic clock. */
+    totalMs: number;
+    /** Client phases in start order. They follow each other, except `view` and `token` at the end of open(), which run together. */
+    phases: TimingPhase[];
+    retries: RetryRecord[];
+    /** Null when the call involved no operation (e.g. open() of a workspace that was already running). */
+    server: ServerTiming | null;
+    /**
+     * totalMs − server.totalMs: time the caller spent outside the operation (network and TLS, the held request's
+     * transit, polling latency, the view read and token). Null when the operation did not finish, or began before this
+     * call (a joined open or resume).
+     */
+    outsideServerMs: number | null;
+}
+interface EventBase {
+    action: LifecycleAction | 'tool';
+    workspaceId: string | null;
+    operationId: string | null;
+    /** Milliseconds since the call began. */
+    atMs: number;
+}
+/**
+ * - `phase`: a phase began (live progress: "capacity_pending: no_ready_host"). `tool` phases come from tool calls.
+ * - `retry`: a request is retried after a transient failure (also emitted for tool calls, action `tool`).
+ * - `done`: the call ended, successfully or not, with its full timing.
+ */
+export type ProgressEvent = (EventBase & {
+    type: 'phase';
+    phase: LifecyclePhase;
+    reason: string | null;
+}) | (EventBase & {
+    type: 'retry';
+    retry: RetryRecord;
+}) | (EventBase & {
+    type: 'done';
+    timing: LifecycleTiming;
+});
+export type ProgressListener = (event: ProgressEvent) => void;
+/** Calls every listener; a listener that throws never breaks the SDK call. */
+export declare function emitTo(listeners: ReadonlyArray<ProgressListener | undefined>, event: ProgressEvent): void;
+/** Combines listeners (client-level and per call) into one; undefined when there are none. */
+export declare function combineListeners(...listeners: Array<ProgressListener | undefined>): ProgressListener | undefined;
+/** Server timing from an operation as GET /v1/operations/{id} returns it. */
+export declare function serverTiming(op: Operation): ServerTiming;
+/** Why a request failed, in one short phrase (for retry records). */
+export declare function describeFailure(err: unknown, timeoutMs?: number): string;
+export declare class Trace {
+    #private;
+    readonly action: LifecycleAction;
+    workspaceId: string | null;
+    operationId: string | null;
+    constructor(action: LifecycleAction, listener: ProgressListener | undefined, ids?: {
+        workspaceId?: string | null;
+        operationId?: string | null;
+    });
+    /** Milliseconds since the call began. */
+    now(): number;
+    get finished(): LifecycleTiming | null;
+    /** Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase. */
+    phase(phase: LifecyclePhase, reason?: string | null): void;
+    /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
+    span<T>(phase: LifecyclePhase, fn: () => Promise<T>, reason?: string | null): Promise<T>;
+    /** Records an operation snapshot: its ids, the observed state as a phase, and the server timing. */
+    observe(op: Operation): void;
+    retry(r: Omit<RetryRecord, 'atMs'>): void;
+    /** An `onRetry` hook for HttpClient requests made on behalf of this call. */
+    get onRetry(): (r: Omit<RetryRecord, 'atMs'>) => void;
+    /** Ends the call (idempotent) and emits `done`. Pass the error when it failed. */
+    end(error?: unknown): LifecycleTiming;
+}
+/** Runs `fn` under `trace` and ends the trace either way (the error keeps its timing). */
+export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T>;
+/**
+ * A human-readable account of a timing, for logs and bug reports:
+ *
+ *   open 34.18 s, succeeded (workspace <id>, operation <id>)
+ *     client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
+ *     server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
+ *     outside the server: 0.16 s
+ *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
+ */
+export declare function formatTiming(t: LifecycleTiming): string;
+export {};

package/dist/progress.js

@@ -0,0 +1,238 @@
+/** Calls every listener; a listener that throws never breaks the SDK call. */
+export function emitTo(listeners, event) {
+    for (const l of listeners) {
+        if (!l)
+            continue;
+        try {
+            l(event);
+        }
+        catch {
+            // Listener errors are the listener's problem.
+        }
+    }
+}
+/** Combines listeners (client-level and per call) into one; undefined when there are none. */
+export function combineListeners(...listeners) {
+    const ls = listeners.filter((l) => l !== undefined);
+    if (ls.length === 0)
+        return undefined;
+    if (ls.length === 1)
+        return ls[0];
+    return (e) => emitTo(ls, e);
+}
+const round = (ms) => Math.round(ms * 10) / 10;
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
+function diffMs(from, to) {
+    if (!from || !to)
+        return null;
+    const d = Date.parse(to) - Date.parse(from);
+    return Number.isFinite(d) ? d : null;
+}
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/** Server timing from an operation as GET /v1/operations/{id} returns it. */
+export function serverTiming(op) {
+    const r = (op.result ?? {});
+    const host = r.host_timings_ms;
+    let hostTimingsMs = null;
+    if (typeof host === 'object' && host !== null) {
+        hostTimingsMs = {};
+        for (const [k, v] of Object.entries(host))
+            if (num(v) !== null)
+                hostTimingsMs[k] = v;
+    }
+    const startedAt = op.started_at ?? null;
+    return {
+        operationId: op.id,
+        kind: op.kind,
+        state: op.state,
+        queuedMs: diffMs(op.created_at, startedAt),
+        runMs: diffMs(startedAt, op.completed_at),
+        totalMs: diffMs(op.created_at, op.completed_at),
+        startPath: str(r.start_path),
+        warmFallback: str(r.warm_fallback),
+        resumePath: str(r.resume_path),
+        bootToReadyMs: num(r.boot_to_ready_ms),
+        hostTimingsMs,
+    };
+}
+function outcomeOf(err) {
+    const name = err instanceof Error ? err.name : '';
+    if (name === 'OperationFailedError')
+        return 'failed';
+    if (name === 'OperationTimeoutError')
+        return 'timed_out';
+    return 'error';
+}
+/** Why a request failed, in one short phrase (for retry records). */
+export function describeFailure(err, timeoutMs) {
+    if (err instanceof Error) {
+        if (err.name === 'TimeoutError')
+            return timeoutMs !== undefined ? `timeout after ${timeoutMs} ms` : 'timeout';
+        const e = err;
+        if (e.name === 'ShardfluxApiError' || e.name === 'ShardfluxProtocolError')
+            return `HTTP ${e.status}${e.code ? ` ${e.code}` : ''}`;
+        return `network: ${e.cause?.code ?? e.cause?.message ?? e.message}`;
+    }
+    return 'network error';
+}
+export class Trace {
+    action;
+    workspaceId;
+    operationId;
+    #listener;
+    #t0;
+    #phases = [];
+    #retries = [];
+    #current = null;
+    #server = null;
+    #timing = null;
+    constructor(action, listener, ids = {}) {
+        this.action = action;
+        this.#listener = listener;
+        this.workspaceId = ids.workspaceId ?? null;
+        this.operationId = ids.operationId ?? null;
+        this.#t0 = performance.now();
+    }
+    /** Milliseconds since the call began. */
+    now() {
+        return round(performance.now() - this.#t0);
+    }
+    get finished() {
+        return this.#timing;
+    }
+    #emit(event) {
+        if (this.#listener)
+            emitTo([this.#listener], event);
+    }
+    #base() {
+        return { action: this.action, workspaceId: this.workspaceId, operationId: this.operationId, atMs: this.now() };
+    }
+    #close(at) {
+        if (this.#current)
+            this.#current.durationMs = round(at - this.#current.startMs);
+        this.#current = null;
+    }
+    /** Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase. */
+    phase(phase, reason = null) {
+        if (this.#timing)
+            return;
+        if (this.#current && this.#current.phase === phase && this.#current.reason === reason)
+            return;
+        const at = this.now();
+        this.#close(at);
+        this.#current = { phase, reason, operationId: this.operationId, startMs: at, durationMs: 0 };
+        this.#phases.push(this.#current);
+        this.#emit({ ...this.#base(), type: 'phase', phase, reason });
+    }
+    /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
+    async span(phase, fn, reason = null) {
+        this.#close(this.now());
+        const entry = { phase, reason, operationId: this.operationId, startMs: this.now(), durationMs: 0 };
+        this.#phases.push(entry);
+        this.#emit({ ...this.#base(), type: 'phase', phase, reason });
+        try {
+            return await fn();
+        }
+        finally {
+            entry.durationMs = round(this.now() - entry.startMs);
+        }
+    }
+    /** Records an operation snapshot: its ids, the observed state as a phase, and the server timing. */
+    observe(op) {
+        // The latest operation wins: a wake that meets a conflict joins the active operation instead of its own.
+        this.operationId = op.id;
+        this.workspaceId ??= op.workspace_id;
+        this.#server = serverTiming(op);
+        if (!TERMINAL.has(op.state))
+            this.phase(op.state, op.state_reason ?? null);
+    }
+    retry(r) {
+        if (this.#timing)
+            return;
+        const record = { atMs: this.now(), ...r };
+        this.#retries.push(record);
+        this.#emit({ ...this.#base(), type: 'retry', retry: record });
+    }
+    /** An `onRetry` hook for HttpClient requests made on behalf of this call. */
+    get onRetry() {
+        return (r) => this.retry(r);
+    }
+    /** Ends the call (idempotent) and emits `done`. Pass the error when it failed. */
+    end(error) {
+        if (this.#timing)
+            return this.#timing;
+        const totalMs = this.now();
+        this.#close(totalMs);
+        const server = this.#server;
+        let outsideServerMs = null;
+        if (server?.totalMs !== null && server?.totalMs !== undefined && server.totalMs <= totalMs)
+            outsideServerMs = round(totalMs - server.totalMs);
+        this.#timing = {
+            action: this.action,
+            outcome: error === undefined ? 'succeeded' : outcomeOf(error),
+            workspaceId: this.workspaceId,
+            operationId: this.operationId,
+            totalMs,
+            phases: this.#phases.map((p) => ({ ...p })),
+            retries: [...this.#retries],
+            server,
+            outsideServerMs,
+        };
+        if (error instanceof Error && 'timing' in error)
+            error.timing ??= this.#timing;
+        this.#emit({ ...this.#base(), type: 'done', timing: this.#timing });
+        return this.#timing;
+    }
+}
+/** Runs `fn` under `trace` and ends the trace either way (the error keeps its timing). */
+export async function traced(trace, fn) {
+    try {
+        const out = await fn();
+        trace.end();
+        return out;
+    }
+    catch (err) {
+        trace.end(err);
+        throw err;
+    }
+}
+const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
+/**
+ * A human-readable account of a timing, for logs and bug reports:
+ *
+ *   open 34.18 s, succeeded (workspace <id>, operation <id>)
+ *     client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
+ *     server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
+ *     outside the server: 0.16 s
+ *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
+ */
+export function formatTiming(t) {
+    const ids = [t.workspaceId ? `workspace ${t.workspaceId}` : null, t.operationId ? `operation ${t.operationId}` : null].filter(Boolean).join(', ');
+    const lines = [`${t.action} ${fmt(t.totalMs)}, ${t.outcome.replace('_', ' ')}${ids ? ` (${ids})` : ''}`];
+    let client = '';
+    t.phases.forEach((p, i) => {
+        const prev = t.phases[i - 1];
+        // A phase that starts before the previous one ended ran alongside it (view and token at the end of open()).
+        const sep = i === 0 ? '' : prev && p.startMs < prev.startMs + prev.durationMs ? ' ∥ ' : ' → ';
+        client += `${sep}${p.phase} ${fmt(p.durationMs)}${p.reason ? ` (${p.reason})` : ''}`;
+    });
+    if (client)
+        lines.push(`  client: ${client}`);
+    const s = t.server;
+    if (s) {
+        const parts = [s.queuedMs !== null ? `queued ${fmt(s.queuedMs)}` : null, s.runMs !== null ? `ran ${fmt(s.runMs)}` : null, s.totalMs !== null ? `total ${fmt(s.totalMs)}` : `still ${s.state}`];
+        const how = [
+            s.startPath ? `start ${s.startPath}${s.warmFallback ? ` (warm fallback: ${s.warmFallback})` : ''}` : null,
+            s.resumePath ? `resume from ${s.resumePath}` : null,
+            s.bootToReadyMs !== null ? `boot to ready ${fmt(s.bootToReadyMs)}` : null,
+            s.hostTimingsMs ? `host ${Object.entries(s.hostTimingsMs).map(([k, v]) => `${k} ${fmt(v)}`).join(', ')}` : null,
+        ].filter(Boolean);
+        lines.push(`  server: ${parts.filter(Boolean).join(', ')}${how.length ? `; ${how.join(', ')}` : ''}`);
+    }
+    if (t.outsideServerMs !== null)
+        lines.push(`  outside the server: ${fmt(t.outsideServerMs)}`);
+    if (t.retries.length)
+        lines.push(`  retries: ${t.retries.length} (${t.retries.map((r) => `${r.request}, ${r.cause}, after ${fmt(r.delayMs)}`).join('; ')})`);
+    return lines.join('\n');
+}

package/dist/secrets.d.ts

@@ -1,12 +1,13 @@
 /**
- * Customer secrets over the application API (/v1). Types are written by hand.
+ * Customer secrets over the application API (/v1). Types are written by hand
+ * (checked against the generated contract in type-checks.ts).
  *
  * A project API key manages the secrets of its own project. Values are
  * write-only: no method here returns one. The cell gateway obtains values at
- * exec/PTY session start through POST /v1/internal/secret-resolutions with the
- * caller's tool token; that endpoint is not part of the customer SDK.
- * Organization-wide secrets and access logs are managed by owners/admins in the
- * browser (/api/v1).
+ * exec/PTY session start with the caller's tool token, for the names bound to
+ * the workspace (`workspace.secrets`, `open({ secrets })`) together with the
+ * call's own `secretRefs`. Organization-wide secrets and access logs are managed
+ * by owners/admins (the API answers 403 to project API keys for those calls).
  */
 import type { ClientContext, Page } from './client.js';
 import type { ToolName } from './tokens.js';
@@ -63,14 +64,64 @@ export interface CreateSecretParams {
     /** Defaults to a fresh key per call so transport retries replay instead of duplicating. */
     idempotencyKey?: string;
 }
+export interface CreateOrganizationSecretParams extends CreateSecretParams {
+    /** Projects whose workspaces may use it: default [] (nowhere until granted); null = every project. */
+    allowedProjectIds?: string[] | null;
+}
 export interface UpdateSecretParams {
     description?: string;
+    /** Organization secrets only. */
+    allowedProjectIds?: string[] | null;
     allowedWorkspaceIds?: string[] | null;
     allowedTools?: ToolName[];
 }
+/** One session-time resolution that matched a secret (granted, denied or failed). Never a value. */
+export interface SecretAccessEvent {
+    id: string;
+    secret_id: string | null;
+    secret_version: number | null;
+    requested_name: string;
+    workspace_id: string;
+    project_id: string;
+    agent_session_id: string | null;
+    principal: {
+        type: 'user' | 'api_key';
+        id: string;
+    };
+    tool: ToolName;
+    outcome: 'granted' | 'denied' | 'failed';
+    /** Closed code for denied/failed: not_found, project_not_allowed, workspace_not_allowed, tool_not_allowed, ... */
+    reason: string | null;
+    ownership_epoch: number | null;
+    request_id: string | null;
+    cell_session_id: string | null;
+    created_at: string;
+}
+/** Status of a bound name: available (injected at the next start), not_allowed (starts are refused with 403), deleted. */
+export type BoundSecretStatus = 'available' | 'not_allowed' | 'deleted';
+/** GET/PUT /v1/workspaces/{id}/secrets: the names bound to a workspace (never values). */
+export interface WorkspaceSecretBindings {
+    workspace_id: string;
+    /** The bound names, in the order they were given. */
+    names: string[];
+    secrets: Array<{
+        name: string;
+        status: BoundSecretStatus;
+        secret_id: string | null;
+        scope: SecretScope | null;
+    }>;
+}
 export declare class SecretsApi {
     #private;
     constructor(ctx: () => ClientContext);
+    /** Creates an organization-wide secret (owners/admins; project API keys get 403). */
+    createOrganization(organizationId: string, params: CreateOrganizationSecretParams): Promise<Secret>;
+    /** Lists organization-wide secrets (metadata only; owners/admins/members, project API keys get 403). */
+    listOrganization(organizationId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        includeDeleted?: boolean;
+    }): Promise<Page<Secret>>;
     /** Creates a project secret (the key's own project). */
     create(projectId: string, params: CreateSecretParams): Promise<Secret>;
     /** Lists a project's secrets (metadata only). */
@@ -95,6 +146,32 @@ export declare class SecretsApi {
         limit?: number;
         cursor?: string;
     }): Promise<Page<SecretVersion>>;
-    /** Deletes (tombstones) the secret and erases its values; resolution stops at once. */
+    /**
+     * Deletes (tombstones) the secret and erases its values; resolution stops at once and the name is removed
+     * from every workspace binding that referred to it.
+     */
     delete(secretId: string): Promise<void>;
+    /** Access log of a secret, newest first (owners/admins; project API keys get 403). */
+    accessEvents(secretId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        outcome?: SecretAccessEvent['outcome'];
+        workspaceId?: string;
+    }): Promise<Page<SecretAccessEvent>>;
+}
+/**
+ * The secret names bound to one workspace (`workspace.secrets`): injected as environment variables into every
+ * exec and PTY start of the workspace, together with the call's own `secretRefs`. Never values.
+ */
+export declare class WorkspaceSecrets {
+    #private;
+    constructor(ctx: ClientContext, workspaceId: string);
+    /** The bound names with their status (available | not_allowed | deleted). */
+    get(): Promise<WorkspaceSecretBindings>;
+    /**
+     * Replaces the binding (`[]` clears it); applies from the next exec/PTY start. Every name must be a secret this
+     * workspace may use, else ShardfluxApiError 422 (details.reason `secret_not_available`, details.names) and
+     * nothing changes.
+     */
+    set(names: readonly string[]): Promise<WorkspaceSecretBindings>;
 }

package/dist/secrets.js

@@ -8,6 +8,25 @@ export class SecretsApi {
     get #auth() {
         return this.#ctx().authorization;
     }
+    /** Creates an organization-wide secret (owners/admins; project API keys get 403). */
+    async createOrganization(organizationId, params) {
+        return this.#ctx().http.json('POST', `/v1/organizations/${encodeURIComponent(organizationId)}/secrets`, {
+            json: {
+                name: params.name,
+                value: params.value,
+                ...(params.description !== undefined ? { description: params.description } : {}),
+                ...(params.allowedProjectIds !== undefined ? { allowed_project_ids: params.allowedProjectIds } : {}),
+                ...(params.allowedWorkspaceIds !== undefined ? { allowed_workspace_ids: params.allowedWorkspaceIds } : {}),
+                ...(params.allowedTools !== undefined ? { allowed_tools: params.allowedTools } : {}),
+            },
+            idempotencyKey: params.idempotencyKey ?? randomId('sdk-secret-'),
+        }, this.#auth);
+    }
+    /** Lists organization-wide secrets (metadata only; owners/admins/members, project API keys get 403). */
+    async listOrganization(organizationId, opts = {}) {
+        const raw = await this.#ctx().http.json('GET', `/v1/organizations/${encodeURIComponent(organizationId)}/secrets`, { query: { limit: opts.limit, cursor: opts.cursor, include_deleted: opts.includeDeleted } }, this.#auth);
+        return toPage(raw);
+    }
     /** Creates a project secret (the key's own project). */
     async create(projectId, params) {
         return this.#ctx().http.json('POST', `/v1/projects/${encodeURIComponent(projectId)}/secrets`, {
@@ -35,6 +54,7 @@ export class SecretsApi {
         return this.#ctx().http.json('PATCH', `/v1/secrets/${encodeURIComponent(secretId)}`, {
             json: {
                 ...(params.description !== undefined ? { description: params.description } : {}),
+                ...(params.allowedProjectIds !== undefined ? { allowed_project_ids: params.allowedProjectIds } : {}),
                 ...(params.allowedWorkspaceIds !== undefined ? { allowed_workspace_ids: params.allowedWorkspaceIds } : {}),
                 ...(params.allowedTools !== undefined ? { allowed_tools: params.allowedTools } : {}),
             },
@@ -49,8 +69,40 @@ export class SecretsApi {
         const raw = await this.#ctx().http.json('GET', `/v1/secrets/${encodeURIComponent(secretId)}/versions`, { query: { limit: opts.limit, cursor: opts.cursor } }, this.#auth);
         return toPage(raw);
     }
-    /** Deletes (tombstones) the secret and erases its values; resolution stops at once. */
+    /**
+     * Deletes (tombstones) the secret and erases its values; resolution stops at once and the name is removed
+     * from every workspace binding that referred to it.
+     */
     async delete(secretId) {
         await this.#ctx().http.json('DELETE', `/v1/secrets/${encodeURIComponent(secretId)}`, {}, this.#auth);
     }
+    /** Access log of a secret, newest first (owners/admins; project API keys get 403). */
+    async accessEvents(secretId, opts = {}) {
+        const raw = await this.#ctx().http.json('GET', `/v1/secrets/${encodeURIComponent(secretId)}/access-events`, { query: { limit: opts.limit, cursor: opts.cursor, outcome: opts.outcome, workspace_id: opts.workspaceId } }, this.#auth);
+        return toPage(raw);
+    }
+}
+/**
+ * The secret names bound to one workspace (`workspace.secrets`): injected as environment variables into every
+ * exec and PTY start of the workspace, together with the call's own `secretRefs`. Never values.
+ */
+export class WorkspaceSecrets {
+    #ctx;
+    #workspaceId;
+    constructor(ctx, workspaceId) {
+        this.#ctx = ctx;
+        this.#workspaceId = workspaceId;
+    }
+    /** The bound names with their status (available | not_allowed | deleted). */
+    get() {
+        return this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.#workspaceId)}/secrets`, {}, this.#ctx.authorization);
+    }
+    /**
+     * Replaces the binding (`[]` clears it); applies from the next exec/PTY start. Every name must be a secret this
+     * workspace may use, else ShardfluxApiError 422 (details.reason `secret_not_available`, details.names) and
+     * nothing changes.
+     */
+    set(names) {
+        return this.#ctx.http.json('PUT', `/v1/workspaces/${encodeURIComponent(this.#workspaceId)}/secrets`, { json: { names: [...names] } }, this.#ctx.authorization);
+    }
 }