Host API reference

All routes are under /api/file-mention, require the plugin request fence, and return { "ok": true, "value": ... } or { "ok": false, "error": { "code": "...", "message": "..." } }.

POST /index

Request:

{ "sessionId": "session-id" }

The Host resolves the workspace from the session. A successful value contains:

{
  "entries": [
    { "relative": "src/", "kind": "dir" },
    { "relative": "src/main.js", "kind": "file", "mtimeMs": 1770000000000, "status": "M" }
  ],
  "files": ["src/main.js"],
  "dirs": ["src/"],
  "strategy": "git",
  "truncated": false,
  "indexVersion": 12,
  "aiincludeFiles": [".aiinclude"],
  "aiincludeTruncated": false
}

entries is canonical. files/dirs remain for compatibility. status is optional (M, A, ??, I, etc.); I means included by .aiinclude.

POST /settings

An empty object reads settings. { "settings": { ... } } replaces them after normalization and atomically persists the result.

Field	Default	Bound / meaning
enabled	true	picker/dock/pre-step master switch
ignorePastedMentions	true	ignore U+2060-protected pasted @ tokens
prioritizeRecentMentions	true	browser-local usage counts break ranking ties
showStatusBadges	true	show changed state in candidate descriptions
indexMaxEntries	20000	100–100000, files + dirs combined
ignoreRules	[]	at most 200 Git-glob-subset strings
uploadFileLimitBytes	52428800	1 MiB–1 GiB
uploadSessionQuotaBytes	262144000	at least per-file, at most 10 GiB
uploadGlobalQuotaBytes	2147483648	at least session, at most 100 GiB
uploadRetentionDays	7	1–365
outputPathCompanion	false	optional turn-tail path surface

Settings live at <DSH_HOME>/storages/dsh-file-mention/settings.json with mode 0600 on first write. A write invalidates all workspace index generations.

POST /status

Request:

{ "sessionId": "session-id" }

Returns path-free aggregates used by the Control Center:

{
  "workspace": "project-name",
  "index": {
    "strategy": "git",
    "indexVersion": 12,
    "files": 314,
    "dirs": 41,
    "dirty": 3,
    "truncated": false,
    "aiincludeFiles": 1
  },
  "uploads": {
    "sessionBytes": 1024,
    "globalBytes": 4096,
    "fileLimitBytes": 52428800,
    "sessionQuotaBytes": 262144000,
    "globalQuotaBytes": 2147483648,
    "retentionDays": 7
  }
}

The value contains counts and the workspace basename, not index paths or upload file names.

POST /maintenance

{ "sessionId": "session-id", "action": "rebuild-index" }

Supported actions:

• rebuild-index: invalidates and rebuilds only the addressed workspace index;
• cleanup-uploads: removes managed files older than uploadRetentionDays.

Success returns the same fresh aggregate value as /status.

POST /upload?sessionId=...&name=...

The body is the raw file. The Host validates the session, quotas, and optional Content-Length, then applies a streaming byte limit. Success returns:

{ "path": "/managed/dsh/uploads/session-id/file.txt", "bytes": 1234 }

path is safe to insert as an absolute managed-upload mention. Existing files are never overwritten.

POST /path-action

{ "sessionId": "session-id", "path": "dist/report.html", "action": "check" }

Actions:

• check: lexical + realpath + stat validation; returns normalized path/kind.
• reveal: repeats the same validation, then reveals the target through an OS helper started with execFile and an argument array.

Only the addressed session workspace and the managed upload root are valid.

.aiinclude reference

The root and up to 49 nested .aiinclude files are discovered. Rules are scoped to the directory containing the file. Blank lines and # comments are ignored.

# add ignored generated Markdown
generated/**/*.md

# remove a subtree; later rules win
!generated/private/**

Supported syntax: *, **, ?, leading /, trailing /, and leading !. It intentionally implements the documented Git-ignore subset, not every edge case of Git's parser.