Skip to content

feat(projects): instructions and reference files, and the prompt's reference note - #935

Merged
OAraLabs merged 45 commits into
mainfrom
feat/chat-projects-files
Nov 15, 2026
Merged

OAraLabs merged 45 commits into
mainfrom
feat/chat-projects-files

Conversation

@OAraLabs

Copy link
Copy Markdown
Owner

Chat projects PR 4 (design #931, 3.4, 3.5, 7). Stacked on #934. Owner-only routes for a project's instructions and reference files, and the prompt's reference note.

  • Instructions (projects/content.py): PROMETHEUS.md at the folder's top is the store. GET returns content, rev (SHA-256/16 of the bytes), max_chars (12,000, the loader's per-file cap) and effective (what the loader reads, deepest first, links marked). PUT needs base_rev: a mismatch is 409 conflict with the current text and rev, nothing written. Written atomically through the folder's directory handle (temp file, fsync, rename). A symlinked or non-regular PROMETHEUS.md is 409 not_a_file. Saving where another convention file sits at the same level is 409 would_shadow unless shadow_ok.
  • Reference files: list / get (no-store, nosniff, attachment) / put (raw body, ?replace=true, read with a running count to 20 MB) / delete, all through a directory handle opened with O_NOFOLLOW; single-segment names; links in reference/ never listed, served, replaced or deleted; a symlinked reference refuses everything; at most 200 files. The body check in server.py lets exactly PUT /api/chat-projects/{id}/files/{name} declare up to 20 MB.
  • Prompt: when a conversation's working directory is a chat project's folder (read-only look-up in the conversation store), the project-files section gets a note listing reference file names, JSON-quoted, labelled as data and not instructions, at most 50 names / 2,000 characters.

Decision under the charter: uploads over REST rather than a WebSocket frame (design P4). The instruction loader itself is unchanged (P13).

Tests: tests/test_chat_projects_files.py, red first. Gate clean; related suites (2,074) pass; reference regenerated.

Review: two independent reviews (file writes and paths).

🤖 Generated with Claude Code

OAraLabs and others added 26 commits November 13, 2026 23:20
…binding stays; root never followed or chmodded (review)

Writes run in a SAVEPOINT under a lock instead of the connection's
context manager, which committed or rolled back other work on the shared
connection; the tables are made with the conversation store's schema so
building the store commits nothing. Filing onto a folder the owner bound
by hand keeps that binding theirs. An existing projects root keeps its
mode and must be a plain directory owned by this user; the folder
returned is resolved. Forgetting a filed session raises rev; an import
key collision is its own error; names are NFC, stripped of control and
format characters, and casefolded.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
… and the daemon's folders

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ade, forgotten sessions not counted (reviews)

Folder checks compare file identity, never spelling: on a case-insensitive
disk a folder typed in another case no longer slips past home, the agent's
home (resolved, including the config and data dirs), the projects root,
another project's folder or a folder that contains home. The projects root
is checked (absolute, its existing parent valid, not under denied_paths)
before anything is made, and a null root means the default. A forgotten
session no longer counts in a project; instructions_rev hashes the whole
file off the event loop; a session bound before its first message cannot
be claimed after a restart; machine gateways and every error carry a kind;
a daemon without a store answers 404 (no projects).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ed; store methods for existence and tool calls (review lows)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ched by folders, not rev (review)

Known-folder paths match only where a path segment ends and begins, so
/srv/app no longer matches /srv/application or /data/srv/app, and the
pattern is built once per tally. Suggestions read only assistant rows
that hold a tool call, and the cache key moves with the projects' ids,
names and folders, so filing a session no longer recomputes every other
one. Case ties pick the spelling the desktop picks; a checkout folder maps
to its project; folders compare without case on macOS; an owner lookup
that fails skips the row.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…der, safe names and downloads (reviews)

Saves and uploads run under a per-folder lock on one directory handle, so
two saves with the same base_rev cannot both win and an upload without
replace never overwrites (an exclusive link). Reads are capped (1 MB for
instructions, 20 MB for a reference file) and a hard-linked file is not
served. effective follows the loader's own config: truncated, omitted and
shadowed_by, and max_chars is the configured per-file cap. Saving keeps
the file's mode; a lone surrogate is a 400; a missing folder is
folder_missing; I/O errors are io_error, never a bare 500. Names a person
would not type (trailing dot or space, odd spaces, non-NFC, over 255
bytes) are refused, and the 200 cap counts files only. Markup downloads
as octet-stream under a sandbox CSP. Instruction and file changes move
rev; the /api 413 carries kind too_large; the prompt note is its own
heading with readable names. The API guide documents the routes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@OAraLabs

Copy link
Copy Markdown
Owner Author

Reviews: two independent reviews, two rounds each. Review 1 (filesystem security): 2 medium (two saves with the same base_rev could both win; reads unbounded and uploads held twice in memory), lows (500s on surrogates/dir swaps/ENOSPC, upload without replace could still overwrite, cap counted dirs/links, mode reset to 0644, leftover temps, hard links served, label and per-name caps, name rules, markup headers, configured cap); all fixed. Review 2 (contract): 4 medium (frames carried an unchanged rev; the middleware 413 had no kind; effective did not match the loader; docs/desktop contract out of date), lows; all fixed, API guide section added. Re-checks: nothing medium or higher; lows taken: effective reads at most the cap, uploads time out, names normalised to NFC, a missed rev never fails a save. Left low: effective's partial-truncation/rules-file nuances, parent-component symlinks in _open_dir, the note keyed on the working directory.

@OAraLabs
OAraLabs marked this pull request as ready for review November 14, 2026 05:17
OAraLabs and others added 14 commits November 14, 2026 17:55
Regenerated with rebaseline-from-exchanges on ubuntu-24.04. Adds the empty
chat_projects, chat_projects_rev and session_chat_projects tables to every
scenario; the other moved lines are the title row's known order race and a
key moving inside an object, both compared order-free.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…h its default

The store reads projects.root, so the template block and the inline
default belong here rather than in the routes PR. Same text as #933, so
the stack merges cleanly.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…utes

# Conflicts:
#	CHANGELOG.md
#	src/prometheus/memory/lcm_conversation_store.py
#	src/prometheus/projects/folders.py
#	src/prometheus/projects/store.py
…utes

# Conflicts:
#	CHANGELOG.md
#	docs/reference/routes.md
#	src/prometheus/web/route_access.py
#	src/prometheus/web/server.py
#	src/prometheus/web/ws_server.py
#	tests/test_route_access.py
…feat/chat-projects-suggestions

# Conflicts:
#	docs/reference/routes.md
…ggestions

# Conflicts:
#	CHANGELOG.md
#	docs/reference/routes.md
#	src/prometheus/web/chat_projects_routes.py
#	src/prometheus/web/route_access.py
@OAraLabs
OAraLabs changed the base branch from feat/chat-projects-suggestions to main November 15, 2026 03:21
OAraLabs and others added 3 commits November 14, 2026 22:22
…into feat/chat-projects-files

# Conflicts:
#	docs/guide/api.md
#	docs/reference/routes.md
# Conflicts:
#	CHANGELOG.md
#	docs/reference/routes.md
#	src/prometheus/web/chat_projects_routes.py
#	src/prometheus/web/route_access.py
@OAraLabs
OAraLabs enabled auto-merge (squash) November 15, 2026 03:24
@OAraLabs
OAraLabs merged commit 256a300 into main Nov 15, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant