dsh-openwrite 0.2.8

package/packages/openwrite-bridge/lib/client.js

@@ -0,0 +1,193 @@
+/** Header OpenWrite requires on every write request (POST/PUT). */
+const WRITE_HEADER = 'X-OpenWrite-Studio';
+/** HTTP header values are bytes, so Unicode paths need explicit wire encoding.
+ * Plain ASCII retains the old contract, including literal percent characters. */
+export function workspaceRootHeaders(root, lowercase = false) {
+    const name = lowercase ? 'x-openwrite-workspace-root' : 'X-OpenWrite-Workspace-Root';
+    return /[^\x20-\x7e]/.test(root)
+        ? { [name]: encodeURIComponent(root), [name + (lowercase ? '-encoding' : '-Encoding')]: 'uri' }
+        : { [name]: root };
+}
+/** A normalized Studio failure: HTTP status plus the server's machine-readable code. */
+export class StudioError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, status, code, details = null) {
+        super(message);
+        this.name = 'StudioError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Narrow `JSON.parse` output to the JsonValue union without `any`. */
+function asJson(value) {
+    // Studio only ever sends JSON; unrepresentable values degrade to null rather
+    // than leaking an untyped `any` into tool output.
+    return (value === undefined ? null : value);
+}
+/** Parse a `Content-Disposition: attachment; filename*=UTF-8''...` header. */
+function parseDispositionFilename(header) {
+    if (header === null)
+        return undefined;
+    const encoded = /filename\*=UTF-8''([^;]+)/i.exec(header);
+    if (encoded?.[1] !== undefined) {
+        try {
+            return decodeURIComponent(encoded[1]);
+        }
+        catch {
+            // Malformed percent-encoding: fall through to the plain filename form.
+        }
+    }
+    const plain = /filename="?([^";]+)"?/i.exec(header);
+    return plain?.[1];
+}
+/** Set query params on a URL, expanding array values into repeated entries. */
+function applyParams(url, params) {
+    for (const [key, value] of Object.entries(params)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(key, item);
+        }
+        else {
+            url.searchParams.set(key, value);
+        }
+    }
+}
+export class StudioClient {
+    connect;
+    baseUrl;
+    timeoutMs;
+    onMutation;
+    /** Workspace context stamped onto every request; undefined for legacy (unscoped) clients. */
+    context;
+    constructor(options) {
+        this.connect = options.connect;
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs;
+        this.onMutation = options.onMutation;
+        this.context = options.context;
+    }
+    /**
+     * Derive a lightweight request-scoped client sharing baseUrl/timeout/onMutation.
+     * Every request it makes carries the §3 context headers, and mutation
+     * notifications report this context so invalidation stays per-root.
+     */
+    scoped(context) {
+        return new StudioClient({ connect: this.connect, baseUrl: this.baseUrl, timeoutMs: this.timeoutMs, onMutation: this.onMutation, context });
+    }
+    /** §3 context headers; empty for a legacy (unscoped) client. */
+    contextHeaders() {
+        const context = this.context;
+        if (context === undefined)
+            return {};
+        const headers = workspaceRootHeaders(context.workspaceRoot);
+        if (context.workspaceId !== undefined)
+            headers['X-OpenWrite-Workspace-Id'] = context.workspaceId;
+        if (context.sessionId !== undefined)
+            headers['X-OpenWrite-Session-Id'] = context.sessionId;
+        if (context.contextEpoch !== undefined)
+            headers['X-OpenWrite-Context-Epoch'] = String(context.contextEpoch);
+        if (context.toolCallId !== undefined)
+            headers['X-OpenWrite-Tool-Call-Id'] = context.toolCallId;
+        if (context.rootCallId !== undefined)
+            headers['X-OpenWrite-Root-Call-Id'] = context.rootCallId;
+        if (context.toolName !== undefined)
+            headers['X-OpenWrite-Tool-Name'] = context.toolName;
+        return headers;
+    }
+    /** GET a JSON endpoint. `params` entries are URL-encoded; undefined values are dropped. */
+    async getJson(path, params = {}, signal) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        applyParams(url, params);
+        const response = await this.request(url, { method: 'GET', headers: this.contextHeaders() }, signal);
+        return this.readJson(response);
+    }
+    /** POST a JSON object with the Studio write protocol header. */
+    async postJson(path, body, signal) {
+        const response = await this.request(new URL(`${this.baseUrl}${path}`), {
+            method: 'POST',
+            headers: { [WRITE_HEADER]: '1', ...this.contextHeaders(), 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        }, signal);
+        const result = await this.readJson(response);
+        this.onMutation?.(path, this.context);
+        return result;
+    }
+    /** PUT a JSON object with the Studio write protocol header. */
+    async putJson(path, body, signal) {
+        const response = await this.request(new URL(`${this.baseUrl}${path}`), {
+            method: 'PUT',
+            headers: { [WRITE_HEADER]: '1', ...this.contextHeaders(), 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        }, signal);
+        const result = await this.readJson(response);
+        this.onMutation?.(path, this.context);
+        return result;
+    }
+    /** GET a file-download endpoint (export), returning the raw bytes and filename. */
+    async download(path, params, signal) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        applyParams(url, params);
+        const response = await this.request(url, { method: 'GET', headers: this.contextHeaders() }, signal);
+        if (!response.ok) {
+            // Error downloads are still JSON payloads.
+            await this.readJson(response);
+        }
+        const content = new Uint8Array(await response.arrayBuffer());
+        return {
+            filename: parseDispositionFilename(response.headers.get('content-disposition')) ?? 'export.bin',
+            contentType: response.headers.get('content-type') ?? 'application/octet-stream',
+            content,
+        };
+    }
+    /** One fetch honoring both the caller's abort signal and the configured timeout. */
+    async request(url, init, signal) {
+        const signals = [AbortSignal.timeout(this.timeoutMs)];
+        if (signal !== undefined)
+            signals.push(signal);
+        try {
+            const connection = await this.connect?.();
+            const target = connection ? new URL(url.pathname + url.search, connection.baseUrl) : url;
+            const headers = connection?.token ? { ...init.headers, Authorization: `Bearer ${connection.token}` } : init.headers;
+            return await fetch(target, { ...init, headers, signal: AbortSignal.any(signals) });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            throw new StudioError(`Studio request failed: ${error instanceof Error ? error.message : String(error)}`, 0, 'NETWORK_ERROR');
+        }
+    }
+    /**
+     * Read a JSON response, throwing a normalized StudioError for non-2xx statuses
+     * and for bodies carrying the server's `{error, code}` contract. Success
+     * envelopes (`{ok: true, data}`) are unwrapped to their `data` payload.
+     */
+    async readJson(response) {
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            throw new StudioError(`Studio returned HTTP ${response.status} with a non-JSON body`, response.status, 'INVALID_RESPONSE');
+        }
+        const body = asJson(parsed);
+        if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+            const error = body['error'];
+            if (typeof error === 'string' && error.length > 0) {
+                const code = typeof body['code'] === 'string' ? body['code'] : 'STUDIO_ERROR';
+                const details = 'details' in body ? body['details'] : null;
+                throw new StudioError(error, response.status, code, details);
+            }
+            // HTTP status remains authoritative even when a proxy or incompatible
+            // server sends a success-shaped envelope with an error status.
+            if (response.ok && body['ok'] === true && 'data' in body)
+                return body['data'];
+        }
+        if (!response.ok) {
+            throw new StudioError(`Studio returned HTTP ${response.status}`, response.status, 'HTTP_ERROR');
+        }
+        return body;
+    }
+}

package/packages/openwrite-bridge/lib/contracts-generated.d.ts

@@ -0,0 +1,367 @@
+/** OpenWrite review v2 decision. Extra keys are allowed (additionalProperties). */
+export interface ReviewV2Decision {
+    schema_version: "openwrite.review.v2";
+    execution_status: "completed" | "partial" | "failed";
+    quality_score: number | null;
+    coverage: number;
+    gate_status: "pass" | "blocked" | "inconclusive";
+    delivery_status: "pass" | "revise" | "blocked" | "inconclusive" | "stale";
+    production_gate_status: "pass" | "revise" | "blocked" | "inconclusive" | "stale" | "disabled" | "disabled_uncalibrated";
+    [key: string]: unknown;
+}
+/** dsh-novel review manifest v2. Extra keys are allowed (additionalProperties). */
+export interface ReviewManifestV2 {
+    schemaVersion: "dsh-novel.review.manifest.v2";
+    recordType: "review";
+    chapterId: string;
+    verdict: "pass" | "fail" | "inconclusive";
+    decisionSource?: "v2" | "v1-adapter";
+    threshold?: number;
+    coverage?: number;
+    qualityScore?: number | null;
+    [key: string]: unknown;
+}
+/** DeliveryManifestV2Stage. Extra keys are allowed (additionalProperties). */
+export interface DeliveryManifestV2Stage {
+    schemaVersion: "dsh-novel.delivery.stage.v2";
+    recordType: "delivery-stage";
+    chapterId: string;
+    stage: string;
+    verdict: "pass" | "fail" | "inconclusive";
+    status: string;
+    evidence: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** dsh-novel delivery manifest v2. Extra keys are allowed (additionalProperties). */
+export interface DeliveryManifestV2 {
+    schemaVersion: "dsh-novel.delivery.manifest.v2";
+    recordType: "chapter-delivery";
+    chapterId: string;
+    novelId?: string;
+    threshold?: number;
+    decisionSource?: "v2" | "v1-adapter";
+    readyForDelivery?: boolean;
+    stages: Record<string, DeliveryManifestV2Stage>;
+    [key: string]: unknown;
+}
+/** dsh-novel delivery stage v2. Extra keys are allowed (additionalProperties). */
+export interface DeliveryStageV2 {
+    schemaVersion: "dsh-novel.delivery.stage.v2";
+    recordType: "delivery-stage";
+    chapterId: string;
+    stage: string;
+    verdict: "pass" | "fail" | "inconclusive";
+    status: string;
+    evidence: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1CandidateUsage. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1CandidateUsage {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    reasoning_tokens?: number | null;
+    total_tokens?: number | null;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1CandidateError. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1CandidateError {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1Candidate. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1Candidate {
+    candidate_id: string;
+    writer_profile: Record<string, unknown>;
+    reliability_status: "completed" | "failed";
+    usage?: ModelBenchmarkV1CandidateUsage | null;
+    cost_usd?: number | null;
+    cost_reported?: boolean;
+    latency_ms?: number | null;
+    error?: ModelBenchmarkV1CandidateError | null;
+    task_type?: "chapter" | "outline";
+    outline_start_chapter?: number;
+    outline_end_chapter?: number;
+    outline_chapter_count?: number;
+    outline_chapters?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1EvaluationUsage. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1EvaluationUsage {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    reasoning_tokens?: number | null;
+    total_tokens?: number | null;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1EvaluationError. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1EvaluationError {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1Evaluation. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1Evaluation {
+    candidate_id: string;
+    reviewer_profile: Record<string, unknown>;
+    execution_status: "completed" | "partial" | "failed";
+    usage?: ModelBenchmarkV1EvaluationUsage | null;
+    cost_usd?: number | null;
+    cost_reported?: boolean;
+    latency_ms?: number | null;
+    error?: ModelBenchmarkV1EvaluationError | null;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1ConfigPipelineNode. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1ConfigPipelineNode {
+    id: string;
+    label: string;
+    depends_on: string[];
+}
+/** ModelBenchmarkV1ConfigPipelineReviewDomain. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1ConfigPipelineReviewDomain {
+    id?: string;
+    label?: string;
+}
+/** ModelBenchmarkV1ConfigPipeline. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1ConfigPipeline {
+    id?: string;
+    execution_mode?: "framework" | "creative";
+    nodes?: ModelBenchmarkV1ConfigPipelineNode[];
+    review_domains?: ModelBenchmarkV1ConfigPipelineReviewDomain[];
+}
+/** ModelBenchmarkV1Config. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1Config {
+    writer_profile_ids: string[];
+    reviewer_profile_ids: string[];
+    repeats?: number;
+    target_words?: number;
+    concurrency?: number;
+    blind_review?: boolean;
+    run_scoped_profiles?: boolean;
+    execution_mode?: "framework" | "creative";
+    task_type?: "chapter" | "outline";
+    outline_start_chapter?: number;
+    outline_end_chapter?: number;
+    outline_chapter_count?: number;
+    pipeline?: ModelBenchmarkV1ConfigPipeline;
+    [key: string]: unknown;
+}
+/** ModelBenchmarkV1Summary. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1Summary {
+    latency_ms_total?: number | null;
+    failed_candidates?: number;
+    [key: string]: unknown;
+}
+/** OpenWrite model benchmark v1 artifact. Extra keys are allowed (additionalProperties). */
+export interface ModelBenchmarkV1 {
+    schema_version: "openwrite.model-benchmark.v1";
+    run_id: string;
+    status: "completed" | "partial" | "failed";
+    context_hash: string;
+    task_id?: string;
+    started_at?: string;
+    candidates: ModelBenchmarkV1Candidate[];
+    evaluations: ModelBenchmarkV1Evaluation[];
+    config: ModelBenchmarkV1Config;
+    summary?: ModelBenchmarkV1Summary;
+    task_type?: "chapter" | "outline";
+    [key: string]: unknown;
+}
+/** OpenWrite independent chat and embedding model surface v1. Extra keys are allowed (additionalProperties). */
+export interface ModelProfileSurfaceV1 {
+    schema_version: "openwrite.model-profile.v1";
+    default_profile_id: string;
+    active_embedding_profile_id: string;
+    profiles: unknown[];
+    embedding_profiles: unknown[];
+    routes: Record<string, string>;
+    [key: string]: unknown;
+}
+/** TaskSurfaceV1TaskProgress. Extra keys are allowed (additionalProperties). */
+export interface TaskSurfaceV1TaskProgress {
+    completed_units: number;
+    total_units: number;
+    ratio: number | null;
+    unit_kind: "candidates" | "evaluations" | "chapters" | "files";
+    [key: string]: unknown;
+}
+/** TaskSurfaceV1TaskError. Extra keys are allowed (additionalProperties). */
+export interface TaskSurfaceV1TaskError {
+    code: string;
+    message: string;
+    recoverable: boolean;
+    failed_stage?: string | null;
+    [key: string]: unknown;
+}
+/** TaskSurfaceV1TaskResultRef. Extra keys are allowed (additionalProperties). */
+export interface TaskSurfaceV1TaskResultRef {
+    type: "chapter" | "review" | "revision" | "research_report" | "benchmark_run" | "import" | "archive";
+    id: string;
+    [key: string]: unknown;
+}
+/** TaskSurfaceV1Task. Extra keys are allowed (additionalProperties). */
+export interface TaskSurfaceV1Task {
+    task_id: string;
+    type: string;
+    status: "pending" | "running" | "awaiting_confirmation" | "completed" | "failed" | "cancelled" | "interrupted";
+    phase: "queued" | "reading" | "preparing" | "model" | "validating" | "committing" | "complete" | null;
+    phase_index: number | null;
+    progress: TaskSurfaceV1TaskProgress | null;
+    attempt: number;
+    retryable: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    error: TaskSurfaceV1TaskError | null;
+    result_ref: TaskSurfaceV1TaskResultRef | null;
+    input_summary: string | null;
+    chapter_id: string | null;
+    schema_version: string;
+    [key: string]: unknown;
+}
+/** OpenWrite task surface v1 (credential-free). Extra keys are allowed (additionalProperties). */
+export interface TaskSurfaceV1 {
+    schema_version: "openwrite.task-surface.v1";
+    phase_order: "queued" | "reading" | "preparing" | "model" | "validating" | "committing" | "complete"[];
+    tasks: TaskSurfaceV1Task[];
+    counts: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1SettingsSearchProvider. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1SettingsSearchProvider {
+    id: "bocha" | "bing" | "jina" | "none";
+    label: string;
+    requires_api_key: boolean;
+    configured: boolean;
+    credential_configured: boolean;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1Settings. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1Settings {
+    search_provider: "bocha" | "bing" | "jina" | "none";
+    search_providers: ResearchSurfaceV1SettingsSearchProvider[];
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1ReportModelProfile. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1ReportModelProfile {
+    id: string | null;
+    label: string | null;
+    model: string | null;
+    provider: string | null;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1ReportSource. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1ReportSource {
+    title: string;
+    url: string;
+    source_type: string;
+    cited: boolean;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1ReportUsage. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1ReportUsage {
+    total_tokens: number | null;
+    reported: boolean;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1ReportCostUsd. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1ReportCostUsd {
+    value: number | null;
+    reported: boolean;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1ReportFailure. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1ReportFailure {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1Report. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1Report {
+    id: string;
+    title: string;
+    status: "succeeded" | "failed" | "needs_human_review" | "unknown";
+    episode_id: string | null;
+    task_id: string | null;
+    created_at: string | null;
+    completed_at: string | null;
+    model_profile: ResearchSurfaceV1ReportModelProfile | null;
+    search_provider: string | null;
+    sources: ResearchSurfaceV1ReportSource[] | null;
+    sources_status: "ok" | "unavailable";
+    source_count: number | null;
+    word_count: number | null;
+    latency_ms: number | null;
+    usage: ResearchSurfaceV1ReportUsage;
+    cost_usd: ResearchSurfaceV1ReportCostUsd;
+    failure: ResearchSurfaceV1ReportFailure | null;
+    metrics: Record<string, unknown>;
+    path: string;
+    bytes: number;
+    [key: string]: unknown;
+}
+/** ResearchSurfaceV1ModelRoute. Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1ModelRoute {
+    profile_id: string;
+    label: string;
+    model: string;
+    provider: string;
+    configured: boolean;
+    compatible: boolean;
+    [key: string]: unknown;
+}
+/** OpenWrite research surface v1 (credential-free). Extra keys are allowed (additionalProperties). */
+export interface ResearchSurfaceV1 {
+    schema_version: "openwrite.research-surface.v1";
+    available: boolean;
+    node_ready: boolean;
+    pnpm_ready: boolean;
+    package_ready: boolean;
+    dependencies_ready: boolean;
+    setup_hint: string;
+    settings: ResearchSurfaceV1Settings;
+    reports: ResearchSurfaceV1Report[];
+    model_route: ResearchSurfaceV1ModelRoute;
+    [key: string]: unknown;
+}
+/** OpenWrite model connection test v1 success payload (chat and embedding variants). Extra keys are allowed (additionalProperties). */
+export interface ModelConnectionTestV1 {
+    ok: true;
+    status: "ok";
+    provider: string;
+    model: string;
+    latency_ms: number;
+    tested_at: string;
+    reply?: string;
+    provider_label?: string;
+    dimension?: number;
+    max_tokens?: number;
+    base_url?: string;
+    vectors?: number;
+    [key: string]: unknown;
+}
+type SchemaMap = Record<string, unknown>;
+/** Minimal JSON Schema subset validator mirroring OpenWrite
+ * `tools/schema_lint.py` and `scripts/schema-lint.mjs`. */
+export declare function validateSchema(value: unknown, schema: SchemaMap, path?: string, root?: SchemaMap): string[];
+/** Validate `value` against the review_v2_decision schema; throw on failure. */
+export declare function validateReviewV2Decision(value: unknown): ReviewV2Decision;
+/** Validate `value` against the review_manifest_v2 schema; throw on failure. */
+export declare function validateReviewManifestV2(value: unknown): ReviewManifestV2;
+/** Validate `value` against the delivery_manifest_v2 schema; throw on failure. */
+export declare function validateDeliveryManifestV2(value: unknown): DeliveryManifestV2;
+/** Validate `value` against the delivery_stage_v2 schema; throw on failure. */
+export declare function validateDeliveryStageV2(value: unknown): DeliveryStageV2;
+/** Validate `value` against the model_benchmark_v1 schema; throw on failure. */
+export declare function validateModelBenchmarkV1(value: unknown): ModelBenchmarkV1;
+/** Validate `value` against the model_profile_surface_v1 schema; throw on failure. */
+export declare function validateModelProfileSurfaceV1(value: unknown): ModelProfileSurfaceV1;
+/** Validate `value` against the task_surface_v1 schema; throw on failure. */
+export declare function validateTaskSurfaceV1(value: unknown): TaskSurfaceV1;
+/** Validate `value` against the research_surface_v1 schema; throw on failure. */
+export declare function validateResearchSurfaceV1(value: unknown): ResearchSurfaceV1;
+/** Validate `value` against the model_connection_test_v1 schema; throw on failure. */
+export declare function validateModelConnectionTestV1(value: unknown): ModelConnectionTestV1;
+export {};