studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/services/personal-folder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-folder.js","sourceRoot":"","sources":["../../src/services/personal-folder.ts"],"names":[],"mappings":"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"}

package/dist/services/scratch-asset-promote.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Promote a conversation-scratch file (image OR doc) into a curated,
+ * library-visible asset (composer-vision-attach / E2a "Save to library",
+ * generalized to any file in PR3).
+ *
+ * Uploaded scratch files live in the `chat-scratch/{sessionId}/{fileId}/{filename}`
+ * keyspace with NO asset-index row — they're ephemeral conversation context,
+ * not catalogued assets (see the E2a section of
+ * `~/.claude/plans/composer-vision-attach.md`). This service is the deliberate
+ * retention path: it copies the scratch bytes into a FREE-STANDING asset (new
+ * immutable assetId + index row + caption trigger), exactly like the global
+ * asset-manager upload, so the result shows up in the asset library.
+ *
+ * Default destination = the reserved workspace-wide "Assets" folder
+ * (`workspace-assets`), which is lazily auto-provisioned and undeletable — so
+ * unlike a per-user personal folder it is ALWAYS resolvable and writable by any
+ * member. The user can then move it into a specific folder via the existing
+ * asset-manager move UI. A caller may override with an explicit `targetRepo`
+ * (the agent tool exposes this as a `folder` argument); we verify write access
+ * to it first.
+ *
+ * The scratch copy is intentionally LEFT in place — it remains the
+ * conversation's vision context and is cleaned up when the chat is deleted.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import type { ChatSessionService } from './chat-session-service.js';
+import type { AuthService, AuthUser } from './auth-service.js';
+/** Typed failure so callers (HTTP route / agent tool) can map to the right
+ *  status / message instead of string-matching. */
+export type PromoteScratchErrorCode = 'SCRATCH_NOT_FOUND' | 'NO_WRITE_ACCESS' | 'NOT_SAVABLE' | 'STORAGE_UNAVAILABLE';
+export declare class PromoteScratchError extends Error {
+    code: PromoteScratchErrorCode;
+    constructor(code: PromoteScratchErrorCode, message: string);
+}
+export interface PromoteScratchResult {
+    assetId: string;
+    /** Canonical immutable public URL of the new asset. */
+    url: string;
+    /** Folder the asset now lives in. */
+    repo: string;
+    filename: string;
+    /** Human display name recorded on the asset row. */
+    displayName: string;
+}
+/**
+ * Promote one scratch file (image OR doc) to a free-standing asset. Returns the
+ * new asset's coordinates. Throws {@link PromoteScratchError} on the typed
+ * failures above.
+ */
+export declare function promoteScratchFileToAssets(workspaceManager: WorkspaceManager, chatSessionService: ChatSessionService, authService: AuthService, args: {
+    sessionId: string;
+    fileId: string;
+    /** The authenticated caller (owner check + write-access check). */
+    user: AuthUser;
+    /** Optional explicit destination folder; defaults to the Assets store. */
+    targetRepo?: string;
+}): Promise<PromoteScratchResult>;

package/dist/services/scratch-asset-promote.js

@@ -0,0 +1,95 @@
+/**
+ * Promote a conversation-scratch file (image OR doc) into a curated,
+ * library-visible asset (composer-vision-attach / E2a "Save to library",
+ * generalized to any file in PR3).
+ *
+ * Uploaded scratch files live in the `chat-scratch/{sessionId}/{fileId}/{filename}`
+ * keyspace with NO asset-index row — they're ephemeral conversation context,
+ * not catalogued assets (see the E2a section of
+ * `~/.claude/plans/composer-vision-attach.md`). This service is the deliberate
+ * retention path: it copies the scratch bytes into a FREE-STANDING asset (new
+ * immutable assetId + index row + caption trigger), exactly like the global
+ * asset-manager upload, so the result shows up in the asset library.
+ *
+ * Default destination = the reserved workspace-wide "Assets" folder
+ * (`workspace-assets`), which is lazily auto-provisioned and undeletable — so
+ * unlike a per-user personal folder it is ALWAYS resolvable and writable by any
+ * member. The user can then move it into a specific folder via the existing
+ * asset-manager move UI. A caller may override with an explicit `targetRepo`
+ * (the agent tool exposes this as a `folder` argument); we verify write access
+ * to it first.
+ *
+ * The scratch copy is intentionally LEFT in place — it remains the
+ * conversation's vision context and is cleaned up when the chat is deleted.
+ */
+import { Workspace } from '../core/workspace.js';
+import { resolveWorkspaceAssetsRepo } from './workspace-assets-folder.js';
+import { deriveAssetDisplayName } from '../core/embeds.js';
+import * as access from './access-control.js';
+export class PromoteScratchError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PromoteScratchError';
+    }
+}
+/**
+ * Promote one scratch file (image OR doc) to a free-standing asset. Returns the
+ * new asset's coordinates. Throws {@link PromoteScratchError} on the typed
+ * failures above.
+ */
+export async function promoteScratchFileToAssets(workspaceManager, chatSessionService, authService, args) {
+    const { sessionId, fileId, user, targetRepo } = args;
+    // 1. Authorize: the scratch row must exist AND be owned by the caller. Same
+    //    fail-closed posture as the serve route — never reveal another user's row.
+    const row = chatSessionService.getScratchFile(sessionId, fileId);
+    if (!row || row.userId !== user.id) {
+        throw new PromoteScratchError('SCRATCH_NOT_FOUND', 'File not found.');
+    }
+    // A library-sourced file is ALREADY a curated asset — nothing to promote.
+    if (row.source === 'library') {
+        throw new PromoteScratchError('NOT_SAVABLE', 'This file is already in your library.');
+    }
+    // 2. Resolve the destination folder.
+    let repo;
+    if (targetRepo) {
+        if (!access.canWriteRepo(user, targetRepo, workspaceManager, authService)) {
+            throw new PromoteScratchError('NO_WRITE_ACCESS', `You can't save to "${targetRepo}".`);
+        }
+        repo = targetRepo;
+    }
+    else {
+        // Default: the reserved workspace-wide Assets store (lazy create-if-missing,
+        // undeletable → always resolvable + writable by any member).
+        const workspace = new Workspace(workspaceManager.getWorkspacePath());
+        repo = await resolveWorkspaceAssetsRepo(workspace, workspaceManager);
+    }
+    // 3. Copy bytes from the scratch blob into a free-standing asset on `repo`.
+    //    The graph for the destination repo records the index row under THIS repo
+    //    and reaches the same workspace-global blob backend the scratch bytes live
+    //    in, so download + upload share one backend.
+    const graph = workspaceManager.getGraph(repo);
+    const svc = graph.getAssetService?.();
+    if (!svc) {
+        throw new PromoteScratchError('STORAGE_UNAVAILABLE', 'Asset storage is not configured.');
+    }
+    const bytes = await svc.download(row.blobKey);
+    const displayName = deriveAssetDisplayName(row.filename) || row.filename;
+    const stored = await graph.uploadAsset('material', // ignored for ownership when `owner` is set
+    'asset', // ignored
+    row.filename, bytes, row.contentType, // preserve the file's MIME (image or doc)
+    {
+        owner: { type: 'folder', id: repo }, // free-standing, folder-owned
+        uploaderUserId: String(user.id),
+        name: displayName,
+    });
+    return {
+        assetId: stored.assetId,
+        url: stored.publicUrl,
+        repo,
+        filename: stored.filename,
+        displayName,
+    };
+}
+//# sourceMappingURL=scratch-asset-promote.js.map

package/dist/services/scratch-asset-promote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-asset-promote.js","sourceRoot":"","sources":["../../src/services/scratch-asset-promote.ts"],"names":[],"mappings":"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"}

package/dist/services/scratch-attachment-service.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Composer attachment resolution (composer-vision-attach, generalized in PR3).
+ *
+ * The chat composer lets a user attach any READABLE file — uploaded to
+ * conversation scratch storage OR picked from the asset library — and have the
+ * agent get its contents for the conversation. The client never sends bytes; it
+ * sends durable **refs**. This service resolves a ref to what the agent actually
+ * consumes:
+ *  - **images** → an `ImageContent` vision block (the model sees the pixels).
+ *  - **docs**   → extracted TEXT injected as context (pdf/docx/xlsx extracted at
+ *    upload and stored; txt/md/csv stored raw). See `chat_scratch_files`.
+ *
+ * The mechanism differs by type; the resolver branches on the scratch row's
+ * `kind` (or, for a library image, the asset index row). Two focused entry
+ * points keep the two concerns clean:
+ *  - `resolveImageRefs` — CURRENT-turn images → vision blocks (PR2 behavior).
+ *  - `resolveDocContext` — doc refs (current turn + replayed from session
+ *    history, D7) → a single capped, prompt-injection-wrapped text block.
+ *
+ * Design (see `~/.claude/plans/composer-vision-attach.md`):
+ *  - **A1 (IDOR):** trust ONLY the index/scratch row, never client-supplied
+ *    values. Repo access (library) / row ownership (scratch) is re-checked on
+ *    EVERY resolve — there is no "trusted" skip.
+ *  - **A3/D8/D11 (limits):** a fixed cross-model MIME allowlist + byte cap +
+ *    count cap for images; per-doc + total char caps for doc text.
+ *  - **D12 (injection):** untrusted doc text is wrapped in labeled delimiters
+ *    with a "data, not instructions" preamble — it must never sit at the
+ *    user-prompt level unmarked.
+ *  - A denied / deleted / unsupported ref never throws and never leaks: it is
+ *    dropped and replaced with a `[file: name]` text placeholder.
+ *
+ * Deps are injected (not WorkspaceManager directly) so the IDOR/format/size
+ * logic is unit-testable without standing up a workspace.
+ */
+import type { ImageContent } from '@mariozechner/pi-ai';
+import type { AssetIndexRow } from './assets/asset-index-service.js';
+import type { ScratchFileKind, ScratchFileSource } from './chat-session-service.js';
+/**
+ * Durable attachment reference the client sends (NOT bytes), a discriminated union:
+ *  - `asset`   — a curated library IMAGE pick; resolved via the asset index + repo
+ *    access. (Library DOC picks are materialized into a scratch row server-side,
+ *    so they arrive as `scratch` refs — there is no asset-doc ref kind.)
+ *  - `scratch` — a conversation file (uploaded image/doc, or a library doc copied
+ *    into scratch); resolved via the chat scratch row + chat ownership. The row's
+ *    `kind` decides image-vs-doc handling; no `repo` (it's not a catalogued asset).
+ */
+export type AttachmentRef = {
+    kind: 'asset';
+    assetId: string;
+    filename: string;
+} | {
+    kind: 'scratch';
+    sessionId: string;
+    fileId: string;
+    filename: string;
+};
+/** Back-compat alias: PR2 shipped the scratch image union with `imageId`. */
+export type ImageRef = AttachmentRef;
+/** Minimal scratch-file metadata the resolver needs (from chat_scratch_files). */
+export interface ScratchFileLite {
+    filename: string;
+    contentType: string;
+    userId: number;
+    blobKey: string;
+    kind: ScratchFileKind;
+    /** Doc text (already capped at upload). Null for images. */
+    extractedText: string | null;
+    /** 'library' rows reference a permanent asset; their repo access must be
+     *  RE-checked on every replay (access may be revoked after attach). */
+    source?: ScratchFileSource;
+    sourceRepo?: string | null;
+}
+/**
+ * Normalize a possibly-legacy/loosely-typed ref into the tagged union, or null
+ * if it carries neither a usable asset nor scratch identity. Defensive parsing
+ * for `chat_messages.meta` (PR2 refs carry `imageId`, not `fileId`; older refs
+ * may lack `kind`).
+ */
+export declare function normalizeAttachmentRef(raw: unknown): AttachmentRef | null;
+/** PR2 export name kept for back-compat importers. */
+export declare const normalizeImageRef: typeof normalizeAttachmentRef;
+/**
+ * Image MIME types vision models actually decode, cross-model. Mirrors
+ * `CAPTIONABLE_MIME` in asset-caption-service.ts — Anthropic + most providers
+ * only accept these four; shipping the others 400s. No per-provider matrix (A3).
+ */
+export declare const VISION_MIME_ALLOWLIST: Set<string>;
+/** Doc MIME types the composer extracts text from (D11). pdf/docx/xlsx via the
+ *  shared extractors; txt/md/csv read raw. */
+export declare const DOC_MIME_ALLOWLIST: Set<string>;
+/**
+ * The composer-READABLE allowlist (D11): the union of vision images + extractable
+ * docs. This is DELIBERATELY narrower than the asset/import allowlist (which
+ * accepts opaque zip/video/audio that the agent can't read) — every accepted file
+ * must produce either pixels or text. The upload route enforces this.
+ */
+export declare const COMPOSER_READABLE_MIME: Set<string>;
+/**
+ * Max decoded bytes per image. Base64 inflates ~33% into the request body and
+ * large payloads 413/timeout. Matches the caption path's DEFAULT_CAPTION_MAX_BYTES.
+ */
+export declare const VISION_MAX_IMAGE_BYTES: number;
+/** Max bytes for an uploaded DOC (D8). Tighter than the image cap because the
+ *  extractors (pdf-parse/mammoth/SheetJS) run synchronously on the request
+ *  thread — a tight cap keeps extraction latency bounded. */
+export declare const DOC_MAX_UPLOAD_BYTES: number;
+/** Max images carried by a single turn. Vision is metered — keep it bounded. */
+export declare const VISION_MAX_IMAGES = 8;
+/** Per-doc extracted-text cap (chars). ~12k chars ≈ 3k tokens. Doc text is
+ *  STORED truncated to this too (D8), so `chat-sessions.db` can't balloon. */
+export declare const DOC_PER_FILE_CHARS = 12000;
+/** Total doc-context cap across all docs in one turn (chars). ~40k ≈ 10k tokens. */
+export declare const DOC_TOTAL_CHARS = 40000;
+/** Max docs injected into one turn's context. */
+export declare const DOC_MAX_FILES = 5;
+/** The text placeholder substituted for an attachment that couldn't be shown. */
+export declare function attachmentPlaceholder(name: string): string;
+/** PR2 export name kept for back-compat importers. */
+export declare const imagePlaceholder: typeof attachmentPlaceholder;
+/** Prompt used when the user sends attachments with no text (#5). */
+export declare const ATTACHMENT_ONLY_FALLBACK_PROMPT = "Please look at the attached file(s).";
+/** PR2 export name kept for back-compat. */
+export declare const IMAGE_ONLY_FALLBACK_PROMPT = "Please look at the attached file(s).";
+/** #5: a chat turn is valid with text OR at least one attachment (image or doc);
+ *  empty-everything is not. */
+export declare function isValidAttachmentTurn(message: string | undefined | null, attachmentCount: number): boolean;
+/** PR2 export name kept for back-compat. */
+export declare const isValidVisionTurn: typeof isValidAttachmentTurn;
+/**
+ * Compose the user-message text for a (possibly attachment-bearing) turn: the
+ * typed text, or the attachment-only fallback when there's no text but there are
+ * attachments, with any dropped-file placeholders appended. Caller prepends its
+ * own context prefixes (and the doc context block, separately).
+ */
+export declare function composeAttachmentMessageText(messageText: string, hasAttachments: boolean, placeholders?: string[]): string;
+/** PR2 export name kept for back-compat. */
+export declare const composeVisionMessageText: typeof composeAttachmentMessageText;
+/** Turn raw image bytes into the agent runtime's image content block. */
+export declare function bufferToImageContent(buffer: Buffer, mimeType: string): ImageContent;
+/**
+ * Injected dependencies. Each is pre-bound to the current request's user, so the
+ * service itself holds no auth knowledge — keeping the access decision in ONE
+ * place (the route) and the resolution logic trivially testable.
+ */
+export interface ResolveAttachmentDeps {
+    /** The authoritative asset-index row for an id, or null if unknown/deleted. */
+    getAssetRow: (assetId: string) => AssetIndexRow | null;
+    /** Whether the CURRENT user may read the given repo. Re-checked every call. */
+    canAccessRepo: (repo: string) => boolean;
+    /** Fetch the stored bytes for an asset (by its index-row repo + filename). */
+    downloadAsset: (repo: string, assetId: string, filename: string) => Promise<Buffer>;
+    /** The scratch metadata row for (sessionId, fileId), or null if unknown. */
+    getScratchRow: (sessionId: string, fileId: string) => ScratchFileLite | null;
+    /** Fetch a scratch image's bytes by its stored blob key. */
+    downloadScratch: (blobKey: string) => Promise<Buffer>;
+    /** The current request's user id — scratch authz is row.userId === this. */
+    currentUserId: number | undefined;
+}
+/** PR2 type name kept for back-compat. */
+export type ResolveImageRefsDeps = ResolveAttachmentDeps;
+export interface ResolvedImages {
+    /** Vision blocks for the refs that resolved cleanly, in input order. */
+    blocks: ImageContent[];
+    /** `[file: name]` notes for refs that were dropped (deleted/denied/etc.). */
+    placeholders: string[];
+}
+/**
+ * Resolve client refs → vision blocks. Handles only IMAGE refs (library `asset`
+ * images + `scratch` rows whose `kind==='image'`); doc refs are skipped here
+ * (they flow through {@link resolveDocContext}). Never throws for a bad/forbidden
+ * ref — it drops to a placeholder. Resolves at most `VISION_MAX_IMAGES`.
+ */
+export declare function resolveImageRefs(refs: AttachmentRef[] | undefined | null, deps: ResolveAttachmentDeps): Promise<ResolvedImages>;
+export interface ResolvedDocs {
+    /** A single text block to append to the prompt (already injection-wrapped +
+     *  capped), or '' if no docs resolved. */
+    docContext: string;
+    /** `[file: name]` notes for doc refs that were dropped. */
+    placeholders: string[];
+}
+/** One resolved doc's text, pre-wrap. */
+interface DocPart {
+    filename: string;
+    text: string;
+}
+/**
+ * Resolve doc refs → ONE prompt-appendable text block (D7 replay target).
+ * Handles only `scratch` rows whose `kind==='doc'` (image/asset refs are skipped
+ * here). Pass the union of the current turn's refs AND the doc refs replayed from
+ * session history — duplicates (same sessionId+fileId) are de-duped. Applies the
+ * per-doc + total caps (D1/D8) and wraps the result so the model treats it as
+ * data, not instructions (D12). Synchronous: text is already stored on the row.
+ */
+export declare function resolveDocContext(refs: AttachmentRef[] | undefined | null, deps: ResolveAttachmentDeps): ResolvedDocs;
+export declare function wrapDocContext(parts: DocPart[]): string;
+export {};