@agent-native/core 0.99.3 → 0.100.0

package/src/templates/workspace-core/.agents/skills/agent-page/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: agent-page
+description: >-
+  The full-page Agent surface (/agent) with Context, Files, Connections, Jobs,
+  and Access tabs. Use when mounting the Agent page in a template, adding an
+  app-specific tab, surfacing context transparency, MCP servers, A2A agents,
+  recurring jobs, or external-client connect flows in the UI.
+metadata:
+  internal: true
+---
+
+# Agent Page
+
+`AgentTabsPage` (from `@agent-native/core/client`, source
+`packages/core/src/client/agent-page/`) is the canonical full-page surface for
+everything that can influence the agent. Design principles:
+
+- The page answers "what can influence this agent, and why" — it is not a
+  generic admin console.
+- Capability and access stay separate: **Connections** is what this agent can
+  reach; **Access** is who can reach this agent.
+- It is a thin shell that re-hosts existing components (ResourcesPanel, MCP
+  hooks, AgentsSection, context X-Ray, jobs actions) — do not re-implement
+  those surfaces inside it.
+- Context must be inspectable, attributable, and governable — provenance and
+  governance tiers, not just a token meter.
+
+## Tabs
+
+| Tab | Contents |
+| --- | --- |
+| `context` | System-vs-conversation split meter, provenance-grouped system sections (governance tiers: required/inherited/user), live-thread manifest. Backed by `context-preview-get` / `context-manifest-get` (see `context-xray` skill). |
+| `files` | ResourcesPanel (skills, instructions, memory, uploads) with the virtual `mcp-servers/` folder hidden (`showMcpServers={false}`). |
+| `connections` | MCP server management (both scopes, admin-gated org writes) plus A2A remote agents this app can call. |
+| `jobs` | Recurring jobs (personal + org) and automations (personal) with pause/resume/delete (see `recurring-jobs` skill). |
+| `access` | Copyable MCP URL and A2A agent-card URL, per-client connect steps (Claude, ChatGPT, Cursor, Claude Code, Codex, Other) from `packages/core/src/shared/mcp-connect-content.ts` (shared with the `/mcp/connect` route — edit the shared module, never fork copy), static-token fallback link. Grants/scopes/revocation UI is future work. |
+
+## Mounting In A Template
+
+1. Add an `/agent` route following the template's settings-route pattern
+   (`app/routes/agent.tsx` or `_app.agent.tsx`), mounting `AgentTabsPage`.
+   CSR is fine; keep the app shell in `root.tsx` so navigation does not
+   remount it (`client-side-routing` skill).
+2. Add an "Agent" item to primary navigation and the command palette,
+   mirroring the Settings entries. Link-first (`native-navigation` skill).
+3. Pass `agentPageHref="/agent"` to `AgentSidebar` so the sidebar workspace
+   and settings modes link out to the full page.
+4. Hash deep-links work out of the box: `/agent#context`, `/agent#files`,
+   `/agent#connections`, `/agent#jobs`, `/agent#access`.
+5. App-specific additions go in `extraTabs` (same `SettingsTabItem` shape as
+   the settings page); hide built-ins only with `hiddenTabs` when a template
+   genuinely lacks the underlying capability.
+
+## Scope
+
+The page-level Personal/Organization toggle passes `scope` (and
+`canManageOrg`) to every tab via `AgentPageTabProps`. Hide nothing silently:
+if a capability is personal-only today (e.g. automations), the org view says
+so honestly instead of faking an org variant.

package/src/templates/workspace-core/.agents/skills/context-xray/SKILL.md

@@ -20,15 +20,40 @@ counts, then lets the user or agent pin, evict, or restore individual segments.
 | Action | When to use |
 | --- | --- |
 | `context-manifest-get` | Read the current manifest for a thread. Returns token totals, segment status, source, and whether changes are enforceable. |
+| `context-preview-get` | Compose the would-be system context for the current user/org/app without a live thread. Returns labeled system sections with provenance, governance tier, token counts, and bounded previews. Backs the Agent page Context tab. |
 | `context-pin` | Preserve a segment across future compaction/model calls. Use for task specs, acceptance criteria, user constraints, and other durable context. |
 | `context-evict` | Exclude a stale or irrelevant segment from future model calls. Eviction is reversible and never deletes chat history. |
 | `context-restore` | Undo a pin, evict, or summarize directive for a segment. |
 | `context-report` | External hosts can report their visible context inventory. These manifests are advisory unless Agent-Native owns the emitted content. |
 
+## System Sections
+
+Manifests now cover the system-prompt half of context, not just conversation
+segments. Each system section carries a `provenance` label (framework-core,
+actions-prompt, template, enterprise-workspace-core, sql-workspace,
+legacy-app-default, organization, personal, memory, db-schema, tools,
+model-overlay, runtime-context) and a `governance` tier:
+
+- `required` — framework/enterprise policy; can never be altered by the user.
+- `inherited` — template/org/workspace instructions; managed elsewhere,
+  visible here.
+- `user` — personal instructions and memory; editable through Files.
+
+System sections are display-only provenance: they cannot be pinned, evicted,
+or summarized. The persisted manifest stores source refs, scope, content
+hashes, token counts, and bounded previews (~200 chars) — never raw prompt
+bodies; full content stays behind the resource/access model. The in-chat
+X-Ray panel groups these under "System", and the Agent page Context tab
+renders the full breakdown (via `context-preview-get`) with a
+system-vs-conversation split meter. Manifests are the latest snapshot per
+thread; there is no per-iteration history.
+
 ## Rules
 
 - Never evict or summarize protected segments. The manifest marks active-turn
   user/tool/thinking context as `protected`.
+- System sections are never evictable; required/inherited tiers are locked by
+  design — do not present controls that imply otherwise.
 - Prefer pinning the user's task, requirements, and decisions before evicting
   large stale tool results.
 - Eviction excludes content from future model calls; it does not delete the

package/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -28,6 +28,13 @@ For a deliberately isolated app, add that app directly at
 `https://<app>.agent-native.com/mcp` or
 `https://<your-host>/mcp`.
 
+In-app, the Agent page's **Access** tab (`/agent#access`, see the
+`agent-page` skill) is the discoverable home for all of this: it shows the
+app's copyable MCP URL and A2A agent-card URL, per-client setup steps
+(Claude, ChatGPT, Cursor, Claude Code, Codex, Other), and links to the full
+`/mcp/connect` page including the static-token fallback. Point users there
+instead of dictating URLs in chat.
+
 OAuth-capable hosts should use the standard remote MCP OAuth flow. Claude
 connectors and Claude Code `/mcp` authentication discover the protected
 resource, open the Agent-Native authorization page, and store their own tokens.

package/src/templates/workspace-core/.agents/skills/recurring-jobs/SKILL.md

@@ -29,6 +29,15 @@ Recurring jobs are scheduled tasks the agent executes automatically on a cron sc
 | `manage-jobs` | `list`     | List all jobs and their status                             |
 | `manage-jobs` | `update`   | Update schedule, instructions, or toggle enabled           |
 
+## UI Surface
+
+Users can see and manage jobs without the agent on the Agent page's Jobs tab
+(`/agent#jobs`, `AgentJobsTab` in `packages/core/src/client/agent-page/`):
+recurring jobs (personal and organization scope) with pause/resume/delete and
+run status, plus automations (personal-only today). Backed by the scoped
+list/manage actions in `packages/core/src/jobs/actions/` — direct users there
+instead of describing job files when they just want to view or toggle jobs.
+
 ## Key Files
 
 | File                                  | Purpose                                                  |