@hivemagnus/ardent-studio 0.0.0-stage → 0.1.0

package/dist/clients/hivemem.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import type { ServiceTokenProvider } from './service-token.js';
+export declare class HiveMemError extends Error {
+    readonly status: number;
+    name: string;
+    constructor(message: string, status: number);
+}
+export interface KnowledgeChunk {
+    chunk_key: string;
+    content: string;
+    content_hash: string;
+    heading?: string | null;
+    tags?: string[];
+}
+export interface KnowledgeSyncRequest {
+    mode: 'preview' | 'apply';
+    workspace_id: string;
+    project_id: string;
+    source_id: string;
+    source_uri: string;
+    revision: string;
+    observed_at: string;
+    expires_at?: string | null;
+    chunks: KnowledgeChunk[];
+}
+export declare const knowledgeSyncResponseSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        preview: "preview";
+        apply: "apply";
+    }>;
+    workspace_id: z.ZodString;
+    project_id: z.ZodString;
+    source_id: z.ZodString;
+    revision: z.ZodString;
+    created: z.ZodNumber;
+    superseded: z.ZodNumber;
+    retired: z.ZodNumber;
+    unchanged: z.ZodNumber;
+}, z.core.$loose>;
+export type KnowledgeSyncResponse = z.infer<typeof knowledgeSyncResponseSchema>;
+export declare const workspaceSchema: z.ZodObject<{
+    workspace_id: z.ZodString;
+    owner_agent_id: z.ZodString;
+    deleted_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+/** HiveMem limits one source sync to 500 chunks, 64 KiB per chunk and 4 MiB in total. */
+export declare const HIVEMEM_MAX_CHUNKS = 500;
+export declare const HIVEMEM_MAX_CHUNK_BYTES = 65536;
+export declare const HIVEMEM_MAX_SYNC_BYTES: number;
+export declare function chunkHash(content: string): string;
+export interface HiveMemClientOptions {
+    baseUrl: string;
+    tokens: Pick<ServiceTokenProvider, 'token' | 'invalidate'>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare class HiveMemClient {
+    private readonly options;
+    private readonly request;
+    private readonly baseUrl;
+    constructor(options: HiveMemClientOptions);
+    /** Unauthenticated liveness of the HiveMem service. */
+    health(): Promise<{
+        status: string;
+    }>;
+    /** Create the project workspace. HiveMem returns the existing workspace when it already exists. */
+    ensureWorkspace(input: {
+        workspace_id: string;
+        title: string;
+        description?: string;
+        metadata?: Record<string, string>;
+    }): Promise<{
+        [x: string]: unknown;
+        workspace_id: string;
+        owner_agent_id: string;
+        deleted_at?: string | null | undefined;
+    }>;
+    syncKnowledgeSource(body: KnowledgeSyncRequest): Promise<KnowledgeSyncResponse>;
+    /** Validate, then write: a preview proves the request before anything changes. */
+    syncKnowledgeSourceChecked(body: Omit<KnowledgeSyncRequest, 'mode'>): Promise<{
+        preview: KnowledgeSyncResponse;
+        applied: KnowledgeSyncResponse;
+    }>;
+    private call;
+}

package/dist/clients/hivemem.js

@@ -0,0 +1,89 @@
+// HiveMem holds project knowledge: one workspace per project, with each reference file synced
+// as a revision-aware source (POST /v1/knowledge/sources/sync). ArdentStudio calls it with its
+// own Oathweave service identity (audience `hivemem`), linked in HiveMem's
+// HIVEMEM_OATHWEAVE_SERVICES_JSON with the memories:write and workspaces:write scopes.
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { trimTrailingSlashes } from '../url.js';
+export class HiveMemError extends Error {
+    status;
+    name = 'HiveMemError';
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export const knowledgeSyncResponseSchema = z.object({
+    mode: z.enum(['preview', 'apply']),
+    workspace_id: z.string(),
+    project_id: z.string(),
+    source_id: z.string(),
+    revision: z.string(),
+    created: z.number().int(),
+    superseded: z.number().int(),
+    retired: z.number().int(),
+    unchanged: z.number().int(),
+}).loose();
+export const workspaceSchema = z.object({ workspace_id: z.string(), owner_agent_id: z.string(), deleted_at: z.string().nullable().optional() }).loose();
+/** HiveMem limits one source sync to 500 chunks, 64 KiB per chunk and 4 MiB in total. */
+export const HIVEMEM_MAX_CHUNKS = 500;
+export const HIVEMEM_MAX_CHUNK_BYTES = 65_536;
+export const HIVEMEM_MAX_SYNC_BYTES = 4 * 1024 * 1024;
+export function chunkHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export class HiveMemClient {
+    options;
+    request;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        this.request = options.fetch ?? ((input, init) => fetch(input, init));
+        this.baseUrl = trimTrailingSlashes(options.baseUrl);
+    }
+    /** Unauthenticated liveness of the HiveMem service. */
+    async health() {
+        const response = await this.request(`${this.baseUrl}/v1/health`, { redirect: 'error', signal: AbortSignal.timeout(5_000) });
+        if (!response.ok)
+            throw new HiveMemError(`HiveMem health answered HTTP ${response.status}`, response.status);
+        return z.object({ status: z.string() }).loose().parse(await response.json());
+    }
+    /** Create the project workspace. HiveMem returns the existing workspace when it already exists. */
+    async ensureWorkspace(input) {
+        return workspaceSchema.parse(await this.call('POST', '/v1/workspaces', {
+            workspace_id: input.workspace_id, title: input.title.slice(0, 200), description: input.description ?? null, metadata: input.metadata ?? {},
+        }));
+    }
+    async syncKnowledgeSource(body) {
+        if (body.chunks.length > HIVEMEM_MAX_CHUNKS)
+            throw new HiveMemError(`A source sync holds at most ${HIVEMEM_MAX_CHUNKS} chunks`, 400);
+        return knowledgeSyncResponseSchema.parse(await this.call('POST', '/v1/knowledge/sources/sync', body));
+    }
+    /** Validate, then write: a preview proves the request before anything changes. */
+    async syncKnowledgeSourceChecked(body) {
+        const preview = await this.syncKnowledgeSource({ ...body, mode: 'preview' });
+        const applied = await this.syncKnowledgeSource({ ...body, mode: 'apply' });
+        return { preview, applied };
+    }
+    async call(method, path, body) {
+        const attempt = async () => this.request(`${this.baseUrl}${path}`, {
+            method,
+            headers: { authorization: `Bearer ${await this.options.tokens.token()}`, accept: 'application/json', ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            redirect: 'error',
+            signal: AbortSignal.timeout(this.options.timeoutMs ?? 30_000),
+        });
+        let response = await attempt();
+        if (response.status === 401) {
+            await response.body?.cancel();
+            this.options.tokens.invalidate();
+            response = await attempt();
+        }
+        if (!response.ok) {
+            const detail = await response.json().catch(() => null);
+            const message = typeof detail?.detail === 'string' ? detail.detail : typeof detail?.error === 'string' ? detail.error : `HiveMem answered HTTP ${response.status}`;
+            throw new HiveMemError(message.slice(0, 300), response.status);
+        }
+        return response.status === 204 ? null : response.json();
+    }
+}