@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/annotatedAttachments/AnnotatedAttachmentSessionStore.test.js

@@ -0,0 +1,278 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createDatabaseAdapter } from '../storage/createDatabaseAdapter.js';
+import { ensureAnnotatedAttachmentSessionsSchema } from '../migrations/taskSchemaMigrations.js';
+import { AnnotatedAttachmentSessionStore } from './AnnotatedAttachmentSessionStore.js';
+function makeStore() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-annotated-attachments-'));
+    const dbPath = path.join(root, 'taskforce.db');
+    const db = createDatabaseAdapter({ sqliteDbPath: dbPath });
+    ensureAnnotatedAttachmentSessionsSchema(db);
+    const store = new AnnotatedAttachmentSessionStore(db, 'default');
+    return {
+        root,
+        db,
+        store,
+        cleanup() {
+            db.close();
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+    };
+}
+describe('AnnotatedAttachmentSessionStore', () => {
+    const cleanups = [];
+    afterEach(() => {
+        while (cleanups.length > 0) {
+            cleanups.pop()?.();
+        }
+    });
+    it('creates and reads sessions with normalized ordered annotations', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        const created = ctx.store.create({
+            id: 'session-1',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+            title: 'Homepage review',
+            globalInstruction: 'Review the marked items.',
+            createdByActorId: 'user-1',
+            updatedByActorId: 'user-1',
+            annotations: [
+                {
+                    id: 'b',
+                    kind: 'box',
+                    order: 2,
+                    markerType: 'issue',
+                    instruction: 'Inspect this area.',
+                    x: 0.2,
+                    y: 0.3,
+                    width: 0.4,
+                    height: 0.2,
+                },
+                {
+                    id: 'a',
+                    kind: 'pin',
+                    order: 1,
+                    markerType: 'question',
+                    instruction: 'What should change here?',
+                    x: 0.1,
+                    y: 0.15,
+                },
+            ],
+        });
+        expect(created).toMatchObject({
+            id: 'session-1',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+            title: 'Homepage review',
+            globalInstruction: 'Review the marked items.',
+            createdByActorId: 'user-1',
+            updatedByActorId: 'user-1',
+        });
+        expect(created.annotations.map((annotation) => annotation.id)).toEqual(['a', 'b']);
+    });
+    it('lists active sessions and keeps soft-deleted rows hidden by default', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        ctx.store.create({
+            id: 'session-a',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+        });
+        ctx.store.create({
+            id: 'session-b',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-2',
+        });
+        expect(ctx.store.softDelete('session-b', 'workspace-1')).toBe(true);
+        const active = ctx.store.listForTask('task-1', 'workspace-1');
+        expect(active.map((session) => session.id)).toEqual(['session-a']);
+        const all = ctx.store.listForTask('task-1', 'workspace-1', { includeDeleted: true });
+        expect(all.map((session) => session.id).sort()).toEqual(['session-a', 'session-b']);
+    });
+    it('updates title, instructions, and annotations without changing task identity', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        ctx.store.create({
+            id: 'session-1',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+            title: 'Before',
+            globalInstruction: 'Initial',
+            annotations: [
+                { id: 'a', kind: 'text-note', order: 0, instruction: 'hello', x: 0.4, y: 0.5 },
+            ],
+        });
+        const updated = ctx.store.update({
+            id: 'session-1',
+            workspaceId: 'workspace-1',
+            title: 'After',
+            globalInstruction: 'Revised',
+            updatedByActorId: 'user-2',
+            annotations: [
+                { id: 'pin-1', kind: 'pin', order: 0, instruction: 'look here', x: 0.8, y: 0.9 },
+            ],
+        });
+        expect(updated).toMatchObject({
+            id: 'session-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+            title: 'After',
+            globalInstruction: 'Revised',
+            updatedByActorId: 'user-2',
+        });
+        expect(updated?.annotations).toEqual([
+            { id: 'pin-1', kind: 'pin', order: 0, instruction: 'look here', color: null, x: 0.8, y: 0.9 },
+        ]);
+    });
+    it('lists all workspace sessions and upserts sync records', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        ctx.store.create({
+            id: 'session-a',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+        });
+        const created = ctx.store.upsertForSync({
+            id: 'session-b',
+            workspaceId: 'workspace-1',
+            taskId: 'task-2',
+            baseImageAssetId: 'asset-2',
+            title: 'Synced session',
+            globalInstruction: 'From sync',
+            annotations: [
+                { id: 'note-1', kind: 'text-note', order: 0, instruction: 'synced', x: 0.2, y: 0.4 },
+            ],
+            createdByActorId: 'user-sync',
+            updatedByActorId: 'user-sync',
+            createdAt: '2026-03-26T10:00:00.000Z',
+            updatedAt: '2026-03-26T11:00:00.000Z',
+        });
+        expect(created).toMatchObject({
+            id: 'session-b',
+            taskId: 'task-2',
+            baseImageAssetId: 'asset-2',
+            title: 'Synced session',
+            globalInstruction: 'From sync',
+            createdByActorId: 'user-sync',
+            updatedByActorId: 'user-sync',
+        });
+        const updated = ctx.store.upsertForSync({
+            id: 'session-b',
+            workspaceId: 'workspace-1',
+            taskId: 'task-2',
+            baseImageAssetId: 'asset-2',
+            title: 'Synced session updated',
+            globalInstruction: 'Changed',
+            annotations: [
+                { id: 'pin-2', kind: 'pin', order: 0, instruction: 'updated', x: 0.6, y: 0.7 },
+            ],
+            createdByActorId: 'user-sync',
+            updatedByActorId: 'user-sync-2',
+            createdAt: '2026-03-26T10:00:00.000Z',
+            updatedAt: '2026-03-26T12:00:00.000Z',
+            deletedAt: '2026-03-26T12:30:00.000Z',
+        });
+        expect(updated).toMatchObject({
+            id: 'session-b',
+            title: 'Synced session updated',
+            globalInstruction: 'Changed',
+            updatedByActorId: 'user-sync-2',
+            deletedAt: '2026-03-26T12:30:00.000Z',
+        });
+        const all = ctx.store.listByWorkspace('workspace-1', { includeDeleted: true });
+        expect(all.map((session) => session.id).sort()).toEqual(['session-a', 'session-b']);
+    });
+    it('soft-deletes all active sessions for a base image asset', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        ctx.store.create({
+            id: 'session-a',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+        });
+        ctx.store.create({
+            id: 'session-b',
+            workspaceId: 'workspace-1',
+            taskId: 'task-2',
+            baseImageAssetId: 'asset-1',
+        });
+        ctx.store.create({
+            id: 'session-c',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-2',
+        });
+        expect(ctx.store.softDeleteByImageAsset('asset-1', 'workspace-1')).toBe(2);
+        expect(ctx.store.get('session-a', 'workspace-1')).toBeNull();
+        expect(ctx.store.get('session-b', 'workspace-1')).toBeNull();
+        expect(ctx.store.get('session-c', 'workspace-1')).toMatchObject({ id: 'session-c' });
+        expect(ctx.store.get('session-a', 'workspace-1', { includeDeleted: true })?.deletedAt).toBeTruthy();
+        expect(ctx.store.get('session-b', 'workspace-1', { includeDeleted: true })?.deletedAt).toBeTruthy();
+    });
+    it('includes unattached sessions when includeUnattached is true', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        ctx.store.create({
+            id: 'session-task',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+            title: 'Task-scoped session',
+        });
+        ctx.store.create({
+            id: 'session-unattached',
+            workspaceId: 'workspace-1',
+            taskId: '',
+            baseImageAssetId: 'asset-1',
+            title: 'Unattached session',
+        });
+        ctx.store.create({
+            id: 'session-other-task',
+            workspaceId: 'workspace-1',
+            taskId: 'task-2',
+            baseImageAssetId: 'asset-1',
+            title: 'Other task session',
+        });
+        const withoutUnattached = ctx.store.listForTask('task-1', 'workspace-1', { imageAssetId: 'asset-1' });
+        expect(withoutUnattached.map((s) => s.id)).toEqual(['session-task']);
+        const withUnattached = ctx.store.listForTask('task-1', 'workspace-1', { imageAssetId: 'asset-1', includeUnattached: true });
+        expect(withUnattached.map((s) => s.id).sort()).toEqual(['session-task', 'session-unattached']);
+    });
+    it('soft-deletes only the sessions for one task-image pair', () => {
+        const ctx = makeStore();
+        cleanups.push(() => ctx.cleanup());
+        ctx.store.create({
+            id: 'session-a',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-1',
+        });
+        ctx.store.create({
+            id: 'session-b',
+            workspaceId: 'workspace-1',
+            taskId: 'task-2',
+            baseImageAssetId: 'asset-1',
+        });
+        ctx.store.create({
+            id: 'session-c',
+            workspaceId: 'workspace-1',
+            taskId: 'task-1',
+            baseImageAssetId: 'asset-2',
+        });
+        expect(ctx.store.softDeleteByTaskAndImage('task-1', 'asset-1', 'workspace-1')).toBe(1);
+        expect(ctx.store.get('session-a', 'workspace-1')).toBeNull();
+        expect(ctx.store.get('session-b', 'workspace-1')).toMatchObject({ id: 'session-b' });
+        expect(ctx.store.get('session-c', 'workspace-1')).toMatchObject({ id: 'session-c' });
+        expect(ctx.store.get('session-a', 'workspace-1', { includeDeleted: true })?.deletedAt).toBeTruthy();
+    });
+});

package/dist/annotatedAttachments/payload.d.ts

@@ -0,0 +1,2 @@
+import type { AnnotatedAttachmentAnnotation, AnnotatedAttachmentCropHint } from './types.js';
+export declare function buildAnnotationCropHint(annotation: AnnotatedAttachmentAnnotation): AnnotatedAttachmentCropHint | undefined;

package/dist/annotatedAttachments/payload.js

@@ -0,0 +1,54 @@
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (value <= 0)
+        return 0;
+    if (value >= 1)
+        return 1;
+    return value;
+}
+function clampCrop(crop) {
+    const x = clamp01(crop.x);
+    const y = clamp01(crop.y);
+    const width = clamp01(crop.width);
+    const height = clamp01(crop.height);
+    return {
+        x,
+        y,
+        width: Math.min(width, 1 - x),
+        height: Math.min(height, 1 - y),
+    };
+}
+export function buildAnnotationCropHint(annotation) {
+    if (annotation.kind === 'text-note')
+        return undefined;
+    if (annotation.kind === 'pin') {
+        const side = 0.18;
+        return clampCrop({
+            x: annotation.x - (side / 2),
+            y: annotation.y - (side / 2),
+            width: side,
+            height: side,
+        });
+    }
+    if (annotation.kind === 'box') {
+        const padding = 0.04;
+        return clampCrop({
+            x: annotation.x - padding,
+            y: annotation.y - padding,
+            width: annotation.width + (padding * 2),
+            height: annotation.height + (padding * 2),
+        });
+    }
+    const minX = Math.min(annotation.x, annotation.x2);
+    const minY = Math.min(annotation.y, annotation.y2);
+    const maxX = Math.max(annotation.x, annotation.x2);
+    const maxY = Math.max(annotation.y, annotation.y2);
+    const padding = 0.04;
+    return clampCrop({
+        x: minX - padding,
+        y: minY - padding,
+        width: (maxX - minX) + (padding * 2),
+        height: (maxY - minY) + (padding * 2),
+    });
+}

package/dist/annotatedAttachments/payload.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { buildAnnotationCropHint } from './payload.js';
+describe('buildAnnotationCropHint', () => {
+    it('builds a clamped square crop around a pin marker', () => {
+        const crop = buildAnnotationCropHint({
+            id: 'pin-1',
+            kind: 'pin',
+            order: 0,
+            instruction: 'Check this point',
+            x: 0.05,
+            y: 0.07,
+            color: null,
+        });
+        expect(crop).toEqual({
+            x: 0,
+            y: 0,
+            width: 0.18,
+            height: 0.18,
+        });
+    });
+    it('pads and clamps box annotations', () => {
+        const crop = buildAnnotationCropHint({
+            id: 'box-1',
+            kind: 'box',
+            order: 0,
+            instruction: 'Inspect this region',
+            x: 0.9,
+            y: 0.88,
+            width: 0.2,
+            height: 0.2,
+            color: null,
+        });
+        expect(crop?.x).toBeCloseTo(0.86, 10);
+        expect(crop?.y).toBeCloseTo(0.84, 10);
+        expect(crop?.width).toBeCloseTo(0.14, 10);
+        expect(crop?.height).toBeCloseTo(0.16, 10);
+    });
+    it('builds union crops for arrows and omits crops for text notes', () => {
+        const arrowCrop = buildAnnotationCropHint({
+            id: 'arrow-1',
+            kind: 'arrow',
+            order: 1,
+            instruction: 'Compare these points',
+            x: 0.7,
+            y: 0.6,
+            x2: 0.2,
+            y2: 0.3,
+            color: null,
+        });
+        const noteCrop = buildAnnotationCropHint({
+            id: 'note-1',
+            kind: 'text-note',
+            order: 2,
+            instruction: 'General note',
+            x: 0.5,
+            y: 0.5,
+            color: null,
+        });
+        expect(arrowCrop).toEqual({
+            x: 0.16,
+            y: 0.26,
+            width: 0.58,
+            height: 0.38,
+        });
+        expect(noteCrop).toBeUndefined();
+    });
+});

package/dist/annotatedAttachments/service.d.ts

@@ -0,0 +1,49 @@
+import type { TaskActor } from '../core/Taskforce.js';
+import type { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import { AnnotatedAttachmentSessionStore } from './AnnotatedAttachmentSessionStore.js';
+import type { AnnotatedAttachmentAnnotation, AnnotatedAttachmentPayload, AnnotatedAttachmentSession } from './types.js';
+export interface AnnotatedAttachmentServiceDeps {
+    tenantId: string;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+    sessionStore: AnnotatedAttachmentSessionStore;
+    normalizeWorkspaceId: (workspaceId?: string | null) => string;
+    resolveWorkspaceActor: (workspaceId: string, actorRef: unknown) => TaskActor | null;
+    generateEntityId: (prefix: string) => string;
+    createRuleError: (message: string, statusCode?: number, code?: string) => Error;
+}
+export declare function listAnnotatedAttachmentSessionsService(deps: AnnotatedAttachmentServiceDeps, input: {
+    workspaceId?: string | null;
+    taskId?: string | null;
+    imageAssetId?: string | null;
+    includeDeleted?: boolean;
+}): AnnotatedAttachmentSession[];
+export declare function getAnnotatedAttachmentSessionService(deps: AnnotatedAttachmentServiceDeps, input: {
+    workspaceId?: string | null;
+    sessionId: string;
+    includeDeleted?: boolean;
+}): AnnotatedAttachmentSession | null;
+export declare function createAnnotatedAttachmentSessionService(deps: AnnotatedAttachmentServiceDeps, input: {
+    workspaceId?: string | null;
+    taskId?: string | null;
+    baseImageAssetId: string;
+    title?: string | null;
+    globalInstruction?: string | null;
+    annotations?: AnnotatedAttachmentAnnotation[];
+    actorId?: string | null;
+}): AnnotatedAttachmentSession;
+export declare function updateAnnotatedAttachmentSessionService(deps: AnnotatedAttachmentServiceDeps, input: {
+    workspaceId?: string | null;
+    sessionId: string;
+    title?: string | null;
+    globalInstruction?: string | null;
+    annotations?: AnnotatedAttachmentAnnotation[];
+    actorId?: string | null;
+}): AnnotatedAttachmentSession;
+export declare function deleteAnnotatedAttachmentSessionService(deps: AnnotatedAttachmentServiceDeps, input: {
+    workspaceId?: string | null;
+    sessionId: string;
+}): boolean;
+export declare function buildAnnotatedAttachmentPayloadService(deps: AnnotatedAttachmentServiceDeps, input: {
+    workspaceId?: string | null;
+    sessionId: string;
+}): AnnotatedAttachmentPayload;

package/dist/annotatedAttachments/service.js

@@ -0,0 +1,121 @@
+import { getImageReferenceLabel } from '../utils/imageReferences.js';
+import { buildAnnotationCropHint } from './payload.js';
+function normalizeId(value) {
+    return String(value || '').trim();
+}
+function hydrateSession(deps, session) {
+    return {
+        ...session,
+        createdByActor: session.createdByActorId ? deps.resolveWorkspaceActor(session.workspaceId, session.createdByActorId) : null,
+        updatedByActor: session.updatedByActorId ? deps.resolveWorkspaceActor(session.workspaceId, session.updatedByActorId) : null,
+    };
+}
+function getRequiredImageAsset(deps, workspaceId, taskId, assetId) {
+    const asset = deps.workspaceAssetStore?.get(assetId, workspaceId) || null;
+    if (!asset || asset.deletedAt) {
+        throw deps.createRuleError('Base image asset not found.', 404, 'ANNOTATED_ATTACHMENT_IMAGE_NOT_FOUND');
+    }
+    if (asset.kind !== 'image') {
+        throw deps.createRuleError('Base asset must be an image.', 400, 'ANNOTATED_ATTACHMENT_IMAGE_REQUIRED');
+    }
+    if (!taskId) {
+        return asset;
+    }
+    const linked = deps.workspaceAssetStore?.listLinksForAsset(asset.assetId, workspaceId)
+        .some((entry) => !entry.deletedAt && entry.taskId === taskId);
+    if (!linked) {
+        throw deps.createRuleError('Base image asset must be attached to the target task.', 400, 'ANNOTATED_ATTACHMENT_IMAGE_UNLINKED');
+    }
+    return asset;
+}
+function toImageRef(asset) {
+    const displayName = String(asset.logicalName || asset.originalFilename || asset.assetId).trim() || asset.assetId;
+    return {
+        assetId: asset.assetId,
+        referenceNumber: typeof asset.referenceNumber === 'number' ? asset.referenceNumber : null,
+        referenceLabel: getImageReferenceLabel(asset) || null,
+        storageKey: asset.storageKey,
+        apiUrl: `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`,
+        mimeType: asset.mimeType,
+        originalFilename: asset.originalFilename,
+        logicalName: asset.logicalName,
+        displayName,
+        sizeBytes: asset.sizeBytes,
+        updatedAt: asset.updatedAt,
+    };
+}
+export function listAnnotatedAttachmentSessionsService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const taskId = normalizeId(input.taskId);
+    const imageAssetId = normalizeId(input.imageAssetId);
+    const records = taskId
+        ? deps.sessionStore.listForTask(taskId, workspaceId, { imageAssetId, includeDeleted: input.includeDeleted, includeUnattached: !!imageAssetId })
+        : deps.sessionStore.listByImageAsset(imageAssetId, workspaceId, { includeDeleted: input.includeDeleted });
+    return records.map((session) => hydrateSession(deps, session));
+}
+export function getAnnotatedAttachmentSessionService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const session = deps.sessionStore.get(input.sessionId, workspaceId, { includeDeleted: input.includeDeleted });
+    return session ? hydrateSession(deps, session) : null;
+}
+export function createAnnotatedAttachmentSessionService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const taskId = normalizeId(input.taskId);
+    const baseImageAssetId = normalizeId(input.baseImageAssetId);
+    if (!baseImageAssetId)
+        throw deps.createRuleError('baseImageAssetId is required.', 400, 'ANNOTATED_ATTACHMENT_IMAGE_REQUIRED');
+    getRequiredImageAsset(deps, workspaceId, taskId, baseImageAssetId);
+    const actorId = normalizeId(input.actorId) || null;
+    const created = deps.sessionStore.create({
+        id: deps.generateEntityId('annotated-attachment-session'),
+        workspaceId,
+        taskId,
+        baseImageAssetId,
+        title: input.title,
+        globalInstruction: input.globalInstruction,
+        annotations: Array.isArray(input.annotations) ? input.annotations : [],
+        createdByActorId: actorId,
+        updatedByActorId: actorId,
+    });
+    return hydrateSession(deps, created);
+}
+export function updateAnnotatedAttachmentSessionService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const existing = deps.sessionStore.get(input.sessionId, workspaceId);
+    if (!existing)
+        throw deps.createRuleError('Annotated attachment session not found.', 404, 'ANNOTATED_ATTACHMENT_SESSION_NOT_FOUND');
+    getRequiredImageAsset(deps, workspaceId, existing.taskId, existing.baseImageAssetId);
+    const updated = deps.sessionStore.update({
+        id: input.sessionId,
+        workspaceId,
+        title: input.title,
+        globalInstruction: input.globalInstruction,
+        annotations: input.annotations,
+        updatedByActorId: normalizeId(input.actorId) || null,
+    });
+    return hydrateSession(deps, updated);
+}
+export function deleteAnnotatedAttachmentSessionService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    return deps.sessionStore.softDelete(input.sessionId, workspaceId);
+}
+export function buildAnnotatedAttachmentPayloadService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const session = deps.sessionStore.get(input.sessionId, workspaceId);
+    if (!session)
+        throw deps.createRuleError('Annotated attachment session not found.', 404, 'ANNOTATED_ATTACHMENT_SESSION_NOT_FOUND');
+    const asset = getRequiredImageAsset(deps, workspaceId, session.taskId, session.baseImageAssetId);
+    const annotations = session.annotations.map((annotation) => {
+        const cropHint = buildAnnotationCropHint(annotation);
+        return cropHint ? { ...annotation, cropHint } : { ...annotation };
+    });
+    return {
+        taskId: session.taskId,
+        workspaceId,
+        sessionId: session.id,
+        image: toImageRef(asset),
+        title: session.title,
+        globalInstruction: session.globalInstruction,
+        annotations,
+    };
+}

package/dist/annotatedAttachments/types.d.ts

@@ -0,0 +1,86 @@
+import type { TaskActor } from '../core/Taskforce.js';
+export type AnnotatedAttachmentAnnotationKind = 'pin' | 'arrow' | 'box' | 'text-note';
+export type AnnotatedAttachmentMarkerType = 'question' | 'change' | 'issue' | 'idea' | 'review';
+export interface AnnotatedAttachmentBaseAnnotation {
+    id: string;
+    order: number;
+    kind: AnnotatedAttachmentAnnotationKind;
+    markerType?: AnnotatedAttachmentMarkerType;
+    instruction: string;
+    color?: string | null;
+}
+export interface AnnotatedAttachmentPinAnnotation extends AnnotatedAttachmentBaseAnnotation {
+    kind: 'pin';
+    x: number;
+    y: number;
+}
+export interface AnnotatedAttachmentArrowAnnotation extends AnnotatedAttachmentBaseAnnotation {
+    kind: 'arrow';
+    x: number;
+    y: number;
+    x2: number;
+    y2: number;
+}
+export interface AnnotatedAttachmentBoxAnnotation extends AnnotatedAttachmentBaseAnnotation {
+    kind: 'box';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AnnotatedAttachmentTextNoteAnnotation extends AnnotatedAttachmentBaseAnnotation {
+    kind: 'text-note';
+    x: number;
+    y: number;
+}
+export type AnnotatedAttachmentAnnotation = AnnotatedAttachmentPinAnnotation | AnnotatedAttachmentArrowAnnotation | AnnotatedAttachmentBoxAnnotation | AnnotatedAttachmentTextNoteAnnotation;
+export interface AnnotatedAttachmentSessionRecord {
+    id: string;
+    tenantId: string;
+    workspaceId: string;
+    taskId: string;
+    baseImageAssetId: string;
+    title: string | null;
+    globalInstruction: string | null;
+    annotations: AnnotatedAttachmentAnnotation[];
+    createdByActorId: string | null;
+    updatedByActorId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+export interface AnnotatedAttachmentSession extends AnnotatedAttachmentSessionRecord {
+    createdByActor: TaskActor | null;
+    updatedByActor: TaskActor | null;
+}
+export interface AnnotatedAttachmentImageRef {
+    assetId: string;
+    referenceNumber: number | null;
+    referenceLabel: string | null;
+    storageKey: string;
+    apiUrl: string;
+    mimeType: string;
+    originalFilename: string;
+    logicalName: string | null;
+    displayName: string;
+    sizeBytes: number;
+    updatedAt: string;
+}
+export interface AnnotatedAttachmentCropHint {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type AnnotatedAttachmentPayloadAnnotation = AnnotatedAttachmentAnnotation & {
+    cropHint?: AnnotatedAttachmentCropHint;
+};
+export interface AnnotatedAttachmentPayload {
+    taskId: string;
+    workspaceId: string;
+    sessionId: string;
+    image: AnnotatedAttachmentImageRef;
+    title: string | null;
+    globalInstruction: string | null;
+    annotations: AnnotatedAttachmentPayloadAnnotation[];
+}