@reunionstudio/airlock-mcp 0.1.4 → 0.1.6

package/.agents/skills/airlock-mcp/SKILL.md

@@ -227,6 +227,36 @@ as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`, or
 Use `admin.*` only when the app is intentionally changing Airlock setup or
 running an admin operation.
 
+Restricted references are one-record interaction contracts for read-only
+reference specs. If `agent.describe_spec`, `observe.spec`,
+`observe.spec_config`, or `observe.reference_context` shows
+`restricted_reference` or `reference_config.restricted_reference`, do not
+enumerate the protected reference, build a populated picker, or use broad
+`agent.select_reference_data` for that object path. Get the lookup value from
+the user's case/work context, then call `agent.get_reference_record` with the
+configured `object_key`, lookup value, purpose, and role lens. The procedure
+returns at most one `RECORD`, applies reference row filters, checks active
+`action_limit` Expectations before returning data, and records the safe
+`REFERENCE_READ` event used for usage budgeting. Branch on stable codes such
+as `OK`, `NOT_FOUND`, `NON_UNIQUE_LOOKUP_KEY`, `PURPOSE_REQUIRED`,
+`USAGE_LIMIT_BLOCKED`, and `REFERENCE_READ_EVENT_FAILED`; expose
+`USAGE_CONTEXT` fields such as `action_limit_used` and `action_time_period`.
+For read-only planning and audit, use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+without querying raw reference rows.
+
+Attachments remain governed evidence. Agents should discover and manage them
+through installed Airlock procedures, not by reading Airlock-owned stages or
+generated storage directly. The Streamlit Native App can preview images and
+text inline and can render bounded page-at-a-time PDF previews for files up to
+100 MB and 2,000 pages. PDFs larger than 12 MB require an explicit open action;
+the selected page and next two pages warm a private session cache. Full-file
+download remains a short-lived Snowflake link when available. Successful PDF
+page previews emit metadata-only `ATTACHMENT_PREVIEW` activity, never document
+content or stage URLs. This UI preview capability does not grant MCP clients
+direct attachment bytes.
+
 Help the app follow the loop:
 
 - Observe/read: fetch existing governed data through approved Airlock or

package/README.md

@@ -221,6 +221,37 @@ For app-first work against installed Airlock, start with `observe.procedures`,
 before designing direct SQL helpers. These payloads are intended to be useful
 to agents as well as humans.
 
+Restricted references are one-record interaction contracts. When
+`observe.reference_context`, `observe.spec_config`, or `agent.describe_spec`
+shows `restricted_reference` or `reference_config.restricted_reference`, agents
+must not call broad
+`agent.select_reference_data` for that object path and must not enumerate values
+or build a populated picker from the protected reference. The agent should get
+the lookup value from the user's case/work context, then call
+`agent.get_reference_record` with the configured `object_key`, lookup value,
+purpose, and role lens. The procedure applies configured reference row filters,
+checks active `action_limit` Expectations before returning a record, always
+records the safe `REFERENCE_READ` event used for budgeting, and returns at most
+one `RECORD`. Branch on codes such as `OK`, `NOT_FOUND`,
+`NON_UNIQUE_LOOKUP_KEY`, `PURPOSE_REQUIRED`, `USAGE_LIMIT_BLOCKED`, and
+`REFERENCE_READ_EVENT_FAILED`, and report `USAGE_CONTEXT` fields such as
+`action_limit_used` and `action_time_period`. Auditors and planning agents can
+inspect `observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+without reading raw reference rows.
+
+Airlock's Streamlit Native App can inspect governed attachment evidence without
+moving it into a separate document service. Images and text preview inline.
+PDFs up to 100 MB and 2,000 pages render one selected page at a time; the
+selected page and next two pages are loaded as one bounded window so ordinary
+forward navigation can use the session cache. PDFs larger than 12 MB require an
+explicit open action. Rendering is bounded by time, dimensions, concurrency,
+output size, session storage, and expiry, while full-file access remains a
+short-lived Snowflake download when available. Successful PDF page previews
+emit metadata-only `ATTACHMENT_PREVIEW` activity. This human-facing capability
+does not permit an MCP agent to bypass attachment procedures or read underlying
+stage objects directly.
+
 For governed Markdown knowledge, use the `okf-knowledge-bundle` pattern. It
 sets `core_config.payload_adapter` to `okf_knowledge_bundle` so installed
 Airlock can load locally validated bundles through

package/docs/install-surface.md

@@ -30,6 +30,21 @@ For installed Airlock access, teach the current procedure split:
 administrative mutation. App-first and audit-style workflows should use
 observe payloads for discovery, context, health, access explanation, activity,
 billing events, and governance maps before considering custom SQL helpers.
+When a read-only reference spec declares `restricted_reference` or
+`reference_config.restricted_reference`, agents should avoid broad
+`agent.select_reference_data` reads and use `agent.get_reference_record` for a
+known lookup value and purpose, with `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit.
+
+The installed Streamlit Native App also provides governed attachment
+inspection: inline image/text previews and bounded, page-at-a-time PDF preview
+for documents up to 100 MB and 2,000 pages. The selected PDF page warms the next
+two pages in the session cache; large PDFs require explicit open, and full-file
+access uses Snowflake download links when available. Successful PDF page
+previews emit metadata-only `ATTACHMENT_PREVIEW` activity. This UI capability
+does not grant MCP clients direct stage access.
 
 The connector package and MCP server live in `reunionstudio/airlock-mcp`.
 This workbench provides the spec-building implementation inside that one

package/docs/workflows.md

@@ -172,6 +172,32 @@ For app-first work, start with observe payloads such as `observe.procedures`,
 wrappers such as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`,
 or `admin.list_events`; use observe list/detail procedures instead.
 
+Restricted references are one-record interaction contracts for read-only
+reference specs. When `observe.reference_context`, `observe.spec_config`, or
+`agent.describe_spec` shows `restricted_reference` or
+`reference_config.restricted_reference`, do not enumerate the protected
+reference, build a populated picker, or use broad `agent.select_reference_data`
+for that object path. Get the lookup value from the user's case/work context,
+then call `agent.get_reference_record` with the configured `object_key`, lookup
+value, purpose, and role lens. The procedure returns at most one `RECORD`,
+applies reference row filters, checks active `action_limit` Expectations before
+returning data, and records the safe `REFERENCE_READ` event used for usage
+budgeting. Use `observe.reference_context`, `observe.usage_limits`,
+`observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
+## Governed Attachment Preview
+
+Attachments remain governed evidence. Agents should discover and manage them
+through installed Airlock procedures rather than reading Airlock-owned stages.
+In the Streamlit Native App, images and text can preview inline, and PDFs up to
+100 MB and 2,000 pages can render one selected page at a time. Airlock renders a
+bounded three-page window so the next two pages are normally session-cache
+hits; PDFs larger than 12 MB require an explicit open action. Full-file download
+remains available through a short-lived Snowflake link when the runtime can
+create one. Preview activity emits metadata-only `ATTACHMENT_PREVIEW` events.
+
 The app should follow the loop:
 
 1. Observe/read governed records through approved Airlock or Snowflake surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {

package/patterns/starter-posts/sample.records.json

@@ -5,7 +5,7 @@
     {
       "post_id": "POST-001",
       "reply_to_post_id": "",
-      "submitted_by": "agent.deb",
+      "submitted_by": "agent.csmith",
       "posted_at": "2026-06-13 09:00:00",
       "body": "Please make reimbursements easier to prepare and submit.",
       "tags": "#request #finance #reimbursements",
@@ -19,7 +19,7 @@
           "desired_outcome": "An approved agent can prepare a draft reimbursement with receipt evidence."
         },
         "agent": {
-          "name": "Deb"
+          "name": "csmith"
         }
       }
     }

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.4",
+    version="0.1.6",
     description="Codex-first workbench and CLI for drafting Airlock specs.",
     packages=find_packages("src"),
     package_dir={"": "src"},

package/src/airlock_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Airlock MCP CLI package."""
 
-__version__ = "0.1.4"
+__version__ = "0.1.6"

package/src/airlock_mcp/app_context.py

@@ -44,6 +44,24 @@ timeline. For `alter_spec` activity, use `CHANGED_SECTIONS` and
 Do not use retired admin read wrappers such as `admin.list_specs`,
 `admin.describe_role`, or `admin.list_events`; use the matching observe procedure.
 
+Restricted references are one-record interaction contracts. If a reference
+spec declares `restricted_reference` or `reference_config.restricted_reference`,
+do not enumerate values or use broad `agent.select_reference_data` for that
+object path. Get the lookup value from the user's case/work context and call
+`agent.get_reference_record` with the configured `object_key`, lookup value,
+purpose, and role lens. Use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
+Attachments remain governed evidence. Agents should discover and manage them
+through installed Airlock procedures, not by reading Airlock-owned stages.
+The Streamlit Native App can preview images and text inline and can render
+bounded page-at-a-time PDF previews for files up to 100 MB and 2,000 pages.
+PDFs larger than 12 MB require explicit open; successful page previews emit
+metadata-only `ATTACHMENT_PREVIEW` activity and do not grant MCP clients direct
+attachment bytes.
+
 Do not store credentials here. Do not write directly to Airlock-owned tables,
 stages, generated views, or generated tables. Use approved Airlock/Snowflake
 access paths and submit governed decisions or actions through spec contracts.
@@ -85,6 +103,18 @@ Installed Airlock procedure grammar:
 - `agent.*` is governed agent work in the actor's scope.
 - `admin.*` is administrative mutation. Do not use retired admin read wrappers;
   use observe list/detail procedures instead.
+
+For restricted reference specs, do not enumerate protected object paths or use
+broad `agent.select_reference_data`. Use `agent.get_reference_record` for a
+known lookup value and purpose, and use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit.
+
+For attachments, use installed Airlock procedures and governed UI surfaces.
+The Streamlit Native App can preview images/text and bounded PDF pages, but
+`ATTACHMENT_PREVIEW` activity is metadata-only and MCP clients must not read
+Airlock-owned stages directly.
 """
 
 
@@ -144,6 +174,8 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
             "observe": "read-only governance observation, context, activity, health, billing events, and access explanation",
             "agent": "governed agent work in the actor scope",
             "admin": "administrative mutation and operational changes",
+            "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
+            "attachment_preview": "governed Streamlit preview emits metadata-only ATTACHMENT_PREVIEW; MCP clients do not get direct stage access",
         },
         "specs": entries,
         "tracks": {

package/src/airlock_mcp/bootstrap.py

@@ -127,6 +127,27 @@ activity, use `CHANGED_SECTIONS` and `CHANGED_FIELDS` to triage what changed
 before fetching version snapshots. Do not call retired admin read wrappers such as `admin.list_specs`, `admin.describe_role`,
 or `admin.list_events`; use the matching observe list/detail procedure.
 
+Restricted references are one-record interaction contracts for read-only
+reference specs. If `agent.describe_spec`, `observe.spec_config`, or
+`observe.reference_context` shows `restricted_reference` or
+`reference_config.restricted_reference`, do not enumerate the protected
+reference, build a populated picker, or use broad `agent.select_reference_data`
+for that object path. Get the lookup value from the user's case/work context,
+then call `agent.get_reference_record` with the configured `object_key`, lookup
+value, purpose, and role lens. Use `observe.usage_limits`,
+`observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
+Attachments remain governed evidence. Agents should discover and manage them
+through installed Airlock procedures, not by reading Airlock-owned stages
+directly. The Streamlit Native App can preview images and text inline and can
+render bounded page-at-a-time PDF previews for files up to 100 MB and 2,000
+pages. PDFs larger than 12 MB require an explicit open action; the selected
+page and next two pages warm a private session cache. Successful PDF page
+previews emit metadata-only `ATTACHMENT_PREVIEW` activity and do not grant MCP
+clients direct attachment bytes.
+
 The app may orient the user with summaries, comparisons, rankings, exception
 queues, proposals, or dashboards. It should submit governed choices back
 through an Airlock spec contract. Do not write directly to Airlock-owned tables,

package/src/mcp.mjs

@@ -44,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.4",
+        version: "0.1.6",
       },
       instructions:
         "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",

package/src/text.mjs

@@ -65,6 +65,27 @@ activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
 before fetching version snapshots. Offer to run \`airlock-mcp init-app-context\`
 in the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
 generated helper folders. Help code the app using approved Airlock/Snowflake access paths.
+When a reference spec declares \`restricted_reference\` or
+\`reference_config.restricted_reference\`, do not enumerate values, build a
+populated picker, or call broad \`agent.select_reference_data\`. Get the lookup
+value from the user's case/work context and call
+\`agent.get_reference_record\` for the configured \`object_key\`, purpose, and
+role lens. It returns at most one record, applies reference row filters, checks
+\`action_limit\` before returning data, and always records the safe
+\`REFERENCE_READ\` event used for budgeting. Branch on \`OK\`, \`NOT_FOUND\`,
+\`NON_UNIQUE_LOOKUP_KEY\`, \`PURPOSE_REQUIRED\`, \`USAGE_LIMIT_BLOCKED\`, and
+\`REFERENCE_READ_EVENT_FAILED\`; report \`USAGE_CONTEXT\` fields such as
+\`action_limit_used\` and \`action_time_period\`. Use
+\`observe.reference_context\`, \`observe.usage_limits\`, \`observe.usage_limit\`,
+and \`observe.explain_access(action => 'get_reference_record', object_key => ...)\`
+for read-only planning and audit.
+Attachments remain governed evidence. Agents should discover and manage them
+through installed Airlock procedures, not by reading Airlock-owned stages.
+The Streamlit Native App can preview images/text and bounded page-at-a-time
+PDFs up to 100 MB and 2,000 pages; PDFs larger than 12 MB require explicit
+open. Successful page previews emit metadata-only \`ATTACHMENT_PREVIEW\`
+activity and do not grant MCP clients direct attachment bytes.
+
 Do not use retired admin read wrappers such as
 \`admin.list_specs\`, \`admin.describe_role\`, or \`admin.list_events\`; use
 the matching observe procedure. Do not write directly to Airlock-owned tables
@@ -185,7 +206,13 @@ read-side discovery with observe payloads such as \`observe.procedures\`,
 for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
 triage what changed before fetching version snapshots. Do not use retired admin
 read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
-\`admin.list_events\`. It can
+\`admin.list_events\`. If a reference spec declares \`restricted_reference\` or
+\`reference_config.restricted_reference\`, do not enumerate the protected
+reference; use \`agent.get_reference_record\` for a known lookup value and
+\`observe.usage_limits\` / \`observe.usage_limit\` for budget visibility. It can
+also explain governed attachment preview: Streamlit can preview images/text and
+bounded PDF pages, while \`ATTACHMENT_PREVIEW\` remains metadata-only and agents
+must use Airlock procedures instead of direct stage reads. Airlock MCP can
 seed an app repo with \`airlock/specs.manifest.json\`, spec snapshots, sample
 records, and generated helper folders. The app should submit decisions,
 approvals, actions, comments, or follow-ups through Airlock spec contracts, not