@vertesia/client 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260725.083715Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260717.131047Z",
+  "version": "1.5.0-dev.20260725.083715Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -11,17 +11,17 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@types/node": "^24.13.2",
-    "rolldown": "1.1.4",
+    "@types/node": "^24.13.3",
+    "rolldown": "1.2.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.10",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "eventsource": "^4.1.0",
-    "@llumiverse/common": "1.5.0-dev.20260713.114357Z",
-    "@vertesia/common": "1.5.0-dev.20260717.131047Z",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260717.131047Z"
+    "@llumiverse/common": "1.5.0-dev.20260725.065646Z",
+    "@vertesia/api-fetch-client": "1.5.0-dev.20260725.083715Z",
+    "@vertesia/common": "1.5.0-dev.20260725.083715Z"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "8aaad228827b2927db8e6aa75b27bfac90fec36f",
+  "gitHead": "57bcc2f27dd17b3387f27c18e89329c4c37f98ac",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AppsApi.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+describe('AppsApi', () => {
+    it('starts an in-place version rebuild without a caller-controlled payload', async () => {
+        const requests: Request[] = [];
+        const fetchMock = vi.fn(async () =>
+            Response.json({
+                workflow_id: 'workflow-1',
+                run_id: 'run-1',
+                app_id: 'sample-app',
+                version_id: 'version-1',
+                rebuild_version_record_id: 'record-1',
+            }),
+        );
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio.example.com',
+            storeUrl: 'https://zeno.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        const result = await client.apps.rebuildVersion('record-1');
+
+        expect(result.version_id).toBe('version-1');
+        expect(requests[0]?.method).toBe('POST');
+        expect(requests[0]?.url).toBe('https://studio.example.com/api/v1/apps/versions/record-1/rebuild');
+    });
+
+    it('deletes a version through its dedicated endpoint', async () => {
+        const requests: Request[] = [];
+        const fetchMock = vi.fn(async () =>
+            Response.json({
+                id: 'record-1',
+                app_id: 'sample-app',
+                version_id: 'version-1',
+                deleted: true,
+                warnings: [],
+            }),
+        );
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio.example.com',
+            storeUrl: 'https://zeno.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        const result = await client.apps.deleteVersion('record-1');
+
+        expect(result.deleted).toBe(true);
+        expect(requests[0]?.method).toBe('DELETE');
+        expect(requests[0]?.url).toBe('https://studio.example.com/api/v1/apps/versions/record-1');
+    });
+
+    it('returns the original response bytes and content type', async () => {
+        const requests: Request[] = [];
+        const bytes = new Uint8Array([0, 255, 10, 42]);
+        const fetchMock = vi.fn(
+            async () =>
+                new Response(bytes, {
+                    status: 200,
+                    headers: { 'content-type': 'application/octet-stream' },
+                }),
+        );
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio.example.com',
+            storeUrl: 'https://zeno.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        const response = await client.apps.getRepoFile('sample-app', 'docs/file.bin', { ref: 'feature/demo' });
+
+        expect(response.headers.get('content-type')).toBe('application/octet-stream');
+        expect(new Uint8Array(await response.arrayBuffer())).toEqual(bytes);
+        expect(requests[0]?.url).toBe(
+            'https://studio.example.com/api/v1/apps/sample-app/repo/file?path=docs%2Ffile.bin&ref=feature%2Fdemo',
+        );
+    });
+
+    it('uploads multiple documents as one multipart commit request', async () => {
+        const requests: Request[] = [];
+        const fetchMock = vi.fn(async () =>
+            Response.json({
+                ref: 'main',
+                previous_commit: '1'.repeat(40),
+                commit: '2'.repeat(40),
+                paths: ['docs/guide.md', 'docs/diagram.png'],
+            }),
+        );
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio.example.com',
+            storeUrl: 'https://zeno.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        const result = await client.apps.commitRepoDocuments(
+            'sample-app',
+            [
+                { path: 'docs/guide.md', content: new Blob(['# Guide']), fileName: 'guide.md' },
+                { path: 'docs/diagram.png', content: new Blob([new Uint8Array([1, 2, 3])]), fileName: 'diagram.png' },
+            ],
+            { ref: 'main', expectedHead: '1'.repeat(40), message: 'Add docs' },
+        );
+
+        expect(result.commit).toBe('2'.repeat(40));
+        const request = requests[0];
+        if (!request) {
+            throw new Error('Expected a multipart document request');
+        }
+        expect(request.url).toBe('https://studio.example.com/api/v1/apps/sample-app/repo/documents');
+        expect(request.headers.get('content-type')).toContain('multipart/form-data; boundary=');
+        const form = await request.formData();
+        expect(JSON.parse(String(form.get('metadata')))).toEqual({
+            ref: 'main',
+            expected_head: '1'.repeat(40),
+            message: 'Add docs',
+            files: [
+                { field: 'file_0', path: 'docs/guide.md' },
+                { field: 'file_1', path: 'docs/diagram.png' },
+            ],
+        });
+        const guideFile = form.get('file_0');
+        const diagramFile = form.get('file_1');
+        if (!(guideFile instanceof File) || !(diagramFile instanceof File)) {
+            throw new Error('Expected multipart file entries');
+        }
+        expect(guideFile.name).toBe('guide.md');
+        expect(diagramFile.size).toBe(3);
+    });
+});

package/src/AppsApi.ts

@@ -1,8 +1,9 @@
 import { ApiTopic, type ClientBase, type ServerError } from '@vertesia/api-fetch-client';
 import type {
-    ActivateAppVersionResponse,
     AppBuildProgress,
     AppDeleteSummary,
+    AppDevelopmentTaskDetails,
+    AppDevelopmentTaskList,
     AppInspectionResult,
     AppInstallation,
     AppInstallationKind,
@@ -13,17 +14,25 @@ import type {
     AppManifestData,
     AppPackage,
     AppPackageScope,
-    AppRepoFile,
+    AppRepoBranch,
+    AppRepoCommits,
+    AppRepoDocumentCommit,
     AppRepoRefs,
     AppRepoTree,
+    AppScaffoldProgress,
     AppToolCollection,
     AppVersionListQuery,
     AppVersionRecord,
     CountResult,
+    CreateAppRepoBranchRequest,
+    DeleteAppVersionResponse,
     ProjectRef,
+    PromoteAppVersionResponse,
     RequireAtLeastOne,
     StartAppBuildRequest,
     StartAppBuildResponse,
+    StartAppScaffoldRequest,
+    StartAppScaffoldResponse,
     UpdateAppInstallationToolAllowlistPayload,
     UpsertAppVersionRequest,
     ValidateUrlRequest,
@@ -83,8 +92,16 @@ export default class AppsApi extends ApiTopic {
         return this.get(`/versions/${recordId}`);
     }
 
-    activateVersion(recordId: string): Promise<ActivateAppVersionResponse> {
-        return this.post(`/versions/${recordId}/activate`);
+    promoteVersion(recordId: string): Promise<PromoteAppVersionResponse> {
+        return this.post(`/versions/${recordId}/promote`);
+    }
+
+    rebuildVersion(recordId: string): Promise<StartAppBuildResponse> {
+        return this.post(`/versions/${recordId}/rebuild`);
+    }
+
+    deleteVersion(recordId: string): Promise<DeleteAppVersionResponse> {
+        return this.del(`/versions/${recordId}`);
     }
 
     startBuild(appIdOrRecordId: string, payload: StartAppBuildRequest): Promise<StartAppBuildResponse> {
@@ -97,6 +114,14 @@ export default class AppsApi extends ApiTopic {
         );
     }
 
+    startScaffold(payload: StartAppScaffoldRequest): Promise<StartAppScaffoldResponse> {
+        return this.post('/scaffolds', { payload });
+    }
+
+    getScaffoldProgress(workflowId: string, runId: string): Promise<AppScaffoldProgress> {
+        return this.get(`/scaffolds/${encodeURIComponent(workflowId)}/${encodeURIComponent(runId)}/progress`);
+    }
+
     /**
      * Get the list if tools provided by the given app.
      * @param appId
@@ -128,12 +153,63 @@ export default class AppsApi extends ApiTopic {
     }
 
     /**
-     * Read the UTF-8 content of a single file in the app's git repository (default
-     * branch unless `ref` is given). Read-only; reads live from the git server.
+     * Read the original bytes of a single file in the app's git repository (default
+     * branch unless `ref` is given). The caller decides whether to consume the
+     * successful response as text, a Blob, or an ArrayBuffer.
      */
-    getRepoFile(appIdOrName: string, path: string, options?: { ref?: string }): Promise<AppRepoFile> {
-        return this.get(`/${encodeURIComponent(appIdOrName)}/repo/file`, {
+    async getRepoFile(appIdOrName: string, path: string, options?: { ref?: string }): Promise<Response> {
+        const endpoint = `/${encodeURIComponent(appIdOrName)}/repo/file`;
+        const response = await this.get<Response>(endpoint, {
             query: { path, ref: options?.ref },
+            reader: (rawResponse) => rawResponse,
+        });
+        if (!response.ok) {
+            const payload = await this.readJSONPayload(response);
+            const request = await this.createRequest(response.url || this.getUrl(endpoint), { method: 'GET' });
+            throw this.createServerError(request, response, payload);
+        }
+        return response;
+    }
+
+    /**
+     * Commit one or more files under the repository's allowed document roots.
+     * The Git service currently permits only `docs/`. All files are written in
+     * one commit and `expectedHead` prevents overwriting a concurrent push.
+     */
+    commitRepoDocuments(
+        appIdOrName: string,
+        files: Array<{ path: string; content: Blob; fileName?: string }>,
+        options: { ref: string; expectedHead: string; message?: string },
+    ): Promise<AppRepoDocumentCommit> {
+        const form = new FormData();
+        const metadata = {
+            ref: options.ref,
+            expected_head: options.expectedHead,
+            message: options.message || 'Upload documentation',
+            files: files.map((file, index) => ({ field: `file_${index}`, path: file.path })),
+        };
+        form.append('metadata', JSON.stringify(metadata));
+        files.forEach((file, index) => {
+            form.append(`file_${index}`, file.content, file.fileName || file.path.split('/').pop() || 'document');
+        });
+        return this.post(`/${encodeURIComponent(appIdOrName)}/repo/documents`, {
+            payload: form,
+            jsonPayload: false,
+            timeoutMs: 120_000,
+        });
+    }
+
+    /**
+     * List repository commits newest first, optionally filtered to commits that changed a file.
+     * History starts at the default branch unless a branch, tag, or commit SHA is supplied as `ref`.
+     */
+    getRepoCommits(
+        appIdOrName: string,
+        path?: string,
+        options?: { ref?: string; limit?: number; cursor?: string },
+    ): Promise<AppRepoCommits> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/repo/commits`, {
+            query: { path, ref: options?.ref, limit: options?.limit, cursor: options?.cursor },
         });
     }
 
@@ -146,8 +222,23 @@ export default class AppsApi extends ApiTopic {
         return this.get(`/${encodeURIComponent(appIdOrName)}/repo/refs`);
     }
 
+    /** List mutable development tasks represented by `agent/*` repository branches. */
+    listDevelopmentTasks(appIdOrName: string): Promise<AppDevelopmentTaskList> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/development-tasks`);
+    }
+
+    /** Get a development task and its latest parent Studio Assistant run, when started. */
+    getDevelopmentTask(appIdOrName: string, taskId: string): Promise<AppDevelopmentTaskDetails> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/development-tasks/${encodeURIComponent(taskId)}`);
+    }
+
+    /** Create a repository branch from an existing branch, tag, or commit. */
+    createRepoBranch(appIdOrName: string, payload: CreateAppRepoBranchRequest): Promise<AppRepoBranch> {
+        return this.post(`/${encodeURIComponent(appIdOrName)}/repo/branches`, { payload });
+    }
+
     /**
-     * Get the published package an app exposes, filtered by scope. App-owned (in-code) artifacts are
+     * Get the promoted package an app exposes, filtered by scope. App-owned (in-code) artifacts are
      * package-resolved (no per-id route), so this is how a client reads the full definition — type
      * schema, interaction prompt, process definition, dashboard spec — to visualize an exposed id.
      */

package/src/AuditTrailApi.ts

@@ -1,5 +1,10 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { AuditTrailQuery, AuditTrailResponse } from '@vertesia/common';
+import type {
+    AuditAggregationQuery,
+    AuditAggregationResponse,
+    AuditTrailQuery,
+    AuditTrailResponse,
+} from '@vertesia/common';
 
 export default class AuditTrailApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -24,4 +29,8 @@ export default class AuditTrailApi extends ApiTopic {
         const qs = params.toString();
         return this.get(`/${qs ? `?${qs}` : ''}`);
     }
+
+    aggregate(query: AuditAggregationQuery): Promise<AuditAggregationResponse> {
+        return this.post('/aggregate', { payload: query });
+    }
 }

package/src/ProjectsApi.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+describe('ProjectsApi', () => {
+    it('encodes app View ids as one path segment', async () => {
+        const requests: Request[] = [];
+        const fetchMock = vi.fn(async () => {
+            return new Response(
+                JSON.stringify({
+                    id: 'app:content:document-lib',
+                    name: 'document-lib',
+                    definition: { name: 'Document library' },
+                }),
+                {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                },
+            );
+        });
+        const client = new VertesiaClient({
+            serverUrl: 'https://api.example.com',
+            storeUrl: 'https://api.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.projects.getAppView('project/with/slash', 'app:content:../../environments');
+
+        expect(requests[0]?.url).toBe(
+            'https://api.example.com/api/v1/projects/project%2Fwith%2Fslash/app-views/app%3Acontent%3A..%2F..%2Fenvironments',
+        );
+    });
+});

package/src/ProjectsApi.ts

@@ -7,6 +7,7 @@ import type {
     ICreateProjectPayload,
     InCodeProcessDefinition,
     InCodeTypeDefinition,
+    InCodeViewDefinition,
     Project,
     ProjectConfiguration,
     ProjectIntegrationConfigRequest,
@@ -80,44 +81,54 @@ export default class ProjectsApi extends ApiTopic {
     }
 
     listAppContentTypes(projectId: string, tag?: string): Promise<InCodeTypeDefinition[]> {
-        return this.get(`/${projectId}/app-types`, {
+        return this.get(`/${encodeURIComponent(projectId)}/app-types`, {
             query: { tag },
         });
     }
 
     getAppContentType(projectId: string, typeId: string): Promise<InCodeTypeDefinition> {
-        return this.get(`/${projectId}/app-types/${typeId}`);
+        return this.get(`/${encodeURIComponent(projectId)}/app-types/${encodeURIComponent(typeId)}`);
     }
 
     listAppProcesses(projectId: string, tag?: string): Promise<InCodeProcessDefinition[]> {
-        return this.get(`/${projectId}/app-processes`, {
+        return this.get(`/${encodeURIComponent(projectId)}/app-processes`, {
             query: { tag },
         });
     }
 
     getAppProcess(projectId: string, processId: string): Promise<InCodeProcessDefinition> {
-        return this.get(`/${projectId}/app-processes/${processId}`);
+        return this.get(`/${encodeURIComponent(projectId)}/app-processes/${encodeURIComponent(processId)}`);
+    }
+
+    listAppViews(projectId: string, tag?: string): Promise<InCodeViewDefinition[]> {
+        return this.get(`/${encodeURIComponent(projectId)}/app-views`, {
+            query: { tag },
+        });
+    }
+
+    getAppView(projectId: string, viewId: string): Promise<InCodeViewDefinition> {
+        return this.get(`/${encodeURIComponent(projectId)}/app-views/${encodeURIComponent(viewId)}`);
     }
 
     listAppRenderingTemplates(projectId: string, tag?: string): Promise<RenderingTemplateDefinitionRef[]> {
-        return this.get(`/${projectId}/app-templates`, {
+        return this.get(`/${encodeURIComponent(projectId)}/app-templates`, {
             query: { tag },
         });
     }
 
     getAppRenderingTemplate(projectId: string, templateUri: string): Promise<RenderingTemplateDefinition> {
-        return this.get(`/${projectId}/app-templates/${templateUri}`);
+        return this.get(`/${encodeURIComponent(projectId)}/app-templates/${encodeURIComponent(templateUri)}`);
     }
 
     getCompositeAppConfiguration(projectId: string): Promise<CompositeAppConfig> {
-        return this.get(`/${projectId}/composite-app`);
+        return this.get(`/${encodeURIComponent(projectId)}/composite-app`);
     }
 
     updateCompositeAppConfiguration(
         projectId: string,
         payload: CompositeAppConfigPayload,
     ): Promise<CompositeAppConfig> {
-        return this.put(`/${projectId}/composite-app`, {
+        return this.put(`/${encodeURIComponent(projectId)}/composite-app`, {
             payload,
         });
     }

package/src/ViewsApi.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+describe('ViewsApi', () => {
+    it('keeps CRUD on Studio and proxies execution to Zeno', async () => {
+        const requests: Request[] = [];
+        const fetchMock = vi.fn(async () => {
+            return new Response(JSON.stringify({}), {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+            });
+        });
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio.example.com',
+            storeUrl: 'https://zeno.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.views.retrieve('document-library');
+        await client.views.execute('document-library');
+        await client.views.preview({
+            configuration: {
+                name: 'Document library',
+                description: 'Browse documents.',
+                scope: {},
+            },
+        });
+
+        expect(requests.map((request) => request.url)).toEqual([
+            'https://studio.example.com/api/v1/views/document-library',
+            'https://zeno.example.com/api/v1/view-executions/document-library/execute',
+            'https://zeno.example.com/api/v1/view-executions/preview',
+        ]);
+    });
+});

package/src/ViewsApi.ts

@@ -0,0 +1,60 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    CreateViewExperienceRequest,
+    DeleteByIdResult,
+    ExecuteViewRequest,
+    PreviewViewExperienceRequest,
+    UpdateViewExperienceRequest,
+    ViewExecutionResult,
+    ViewExperience,
+    ViewExperienceListQuery,
+} from '@vertesia/common';
+import type { StoreViewsApi } from './store/ViewsApi.js';
+
+export default class ViewsApi extends ApiTopic {
+    constructor(
+        parent: ClientBase,
+        private readonly executionApi: StoreViewsApi,
+    ) {
+        super(parent, '/api/v1/views');
+    }
+
+    list(query: ViewExperienceListQuery = {}): Promise<ViewExperience[]> {
+        return this.get('/', {
+            query: {
+                limit: query.limit,
+                offset: query.offset,
+            },
+        });
+    }
+
+    create(payload: CreateViewExperienceRequest): Promise<ViewExperience> {
+        return this.post('/', { payload });
+    }
+
+    retrieve(id: string): Promise<ViewExperience> {
+        return this.get(`/${encodeURIComponent(id)}`);
+    }
+
+    update(id: string, payload: UpdateViewExperienceRequest): Promise<ViewExperience> {
+        return this.put(`/${encodeURIComponent(id)}`, { payload });
+    }
+
+    delete(id: string): Promise<DeleteByIdResult> {
+        return this.del(`/${encodeURIComponent(id)}`);
+    }
+
+    /**
+     * Execute a persisted or app-contributed View through the content service.
+     */
+    execute(id: string, payload: ExecuteViewRequest = {}): Promise<ViewExecutionResult> {
+        return this.executionApi.execute(id, payload);
+    }
+
+    /**
+     * Validate and execute an unsaved View through the content service.
+     */
+    preview(payload: PreviewViewExperienceRequest): Promise<ViewExecutionResult> {
+        return this.executionApi.preview(payload);
+    }
+}

package/src/client.ts

@@ -28,6 +28,7 @@ import { VERSION, VERSION_HEADER } from './store/version.js';
 import ToolsApi from './ToolsApi.js';
 import TrainingApi from './TrainingApi.js';
 import UsersApi from './UsersApi.js';
+import ViewsApi from './ViewsApi.js';
 
 /**
  * 1 min threshold constant in ms
@@ -206,6 +207,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
             timeout: opts.timeout,
             fetch: opts.fetch,
         });
+        this.views = new ViewsApi(this, this.store.views);
 
         if (opts.retryPolicy) {
             this.withRetryPolicy(opts.retryPolicy);
@@ -243,7 +245,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     /**
      * Pin the app version this client's requests resolve against. A generated app's UI sets this from
      * its build-time `VITE_APP_VERSION` so studio/zeno resolve its `app:<app>:…` refs against that
-     * published version (candidate testing) instead of current. Pass null/empty to clear (→ current).
+     * exact built version instead of the promoted version. Pass null/empty to clear (→ promoted).
      */
     withAppVersion(version: string | null | undefined) {
         if (!version) {
@@ -425,6 +427,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     apps = new AppsApi(this);
     tools = new ToolsApi(this);
     quota = new QuotaApi(this);
+    views: ViewsApi;
 }
 
 function isApiKey(apiKey: string) {

package/src/index.ts

@@ -18,4 +18,5 @@ export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.js';
 export { default as SecretsApi } from './SecretsApi.js';
 export * from './StreamSource.js';
 export * from './store/index.js';
+export { default as ViewsApi } from './ViewsApi.js';
 export type { AsyncExecutionResult };

package/src/store/AgentsApi.ts

@@ -1,6 +1,7 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import {
     type ActiveWorkstreamsQueryResult,
+    type AgentArtifactContentResponse,
     type AgentArtifactUrlResponse,
     type AgentEvent,
     type AgentMessage,
@@ -41,6 +42,8 @@ import {
     type ToolParameterAnalyticsResponse,
     type TopPrincipalsAnalyticsResponse,
     toAgentMessage,
+    type UpdateAgentArtifactContentPayload,
+    type UpdateAgentArtifactContentResponse,
     type UpdateAgentRunStatusPayload,
     type WorkflowAnalyticsFilterOptionsResponse,
     type WorkflowAnalyticsSummaryQuery,
@@ -734,6 +737,20 @@ export class AgentsApi extends ApiTopic {
         return this.get(`/${id}/artifacts`, { query });
     }
 
+    /** Read a text artifact together with its conditional-write generation token. */
+    getArtifactContent(id: string, path: string): Promise<AgentArtifactContentResponse> {
+        return this.get(`/${id}/artifact-content/${path}`);
+    }
+
+    /** Conditionally replace the text content of an agent artifact. */
+    updateArtifactContent(
+        id: string,
+        path: string,
+        payload: UpdateAgentArtifactContentPayload,
+    ): Promise<UpdateAgentArtifactContentResponse> {
+        return this.put(`/${id}/artifact-content/${path}`, { payload });
+    }
+
     /**
      * Get a signed download URL for an artifact.
      */