diff --git a/AGENTS.md b/AGENTS.md index 55d1dbe..6cd6f48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,9 +12,10 @@ The navigation keeps Home first, then sorts the top-level sections and the pages inside each section alphabetically: -- **Agents (Beta)** - `/developers/*`. Guides cover Agent setup, threads, context, projects, schedules, and preferences. Architecture and the REST API reference live here too, with API pages under `/developers/api-ref/*`. +- **Administration** - `/admin-panel`. Browser-admin access, dashboards, governance records, runtime controls, and network policy. +- **Agents (Beta)** - `/developers/*`. Guides cover Agent setup, threads, context, projects, schedules, preferences, and webhooks. Architecture and the REST API reference live here too, with API pages under `/developers/api-ref/*`. - **App setup** - `/integrations/{github, gmail, google-calendar, slack}`. Per-app permissions and prompts, not feature pages. All of them connect through the Apps tab of the Add MCP dialog. -- **Features** - `/features/*`. Approvals and permissions, Apps and MCP servers, Chat, Confidential mode, Imports, Memory, Skills, and Tasks. +- **Features** - `/features/*`. Approvals and permissions, Apps and MCP servers, Chat, Confidential mode, Imports, Memory, Projects, Skills, and Tasks. - **Get started** - `/going-deeper`, `/introduction`, `/quickstart`. These pages explain the path from first setup to daily use. - **Reference** - `/resources/{faq, pricing, privacy, security}`. Security covers infrastructure; Privacy covers data handling; they're distinct pages. - **Release notes** - `/release-notes`. Customer-facing changes, newest first. diff --git a/content/docs/admin-panel.mdx b/content/docs/admin-panel.mdx new file mode 100644 index 0000000..1513124 --- /dev/null +++ b/content/docs/admin-panel.mdx @@ -0,0 +1,92 @@ +--- +title: Admin panel +sidebarTitle: Admin panel +icon: shield-user +description: Review users, runtimes, recorded model usage, identity and access changes, and network policy from Fluso Admin. +--- + +Fluso Admin is a separate browser interface for authorized operators. It shows account, runtime, usage, and governance records without exposing the content of members' work. + + + Your organization provides its Fluso Admin address and assigns the panel + role. This is separate from the organization role recorded under **Teams & + access**. + + +## Access roles + +The backend checks the administrator role on every request. + +| Role | Access | +| --- | --- | +| Read-only | View dashboards, users, runtimes, usage, access records, and network policy. Export available reports. | +| Read and write | All read-only access, plus runtime controls, plan sponsorship, team and Agent access changes, and network policy changes. | + +The **Admin** organization role does not grant access to Fluso Admin. Panel access uses the separate read-only or read-and-write role assigned by the operator of your deployment. + +## View scope + +**Overview** and **Users** cover the configured sign-in instance. **Teams & access** and **Audit log** show one target account and default to the signed-in administrator. To inspect another account, open it from **Users**, then choose **Manage access** or **Audit trail**. + +## Admin views + +| View | What it shows or controls | +| --- | --- | +| **Overview** | Instance-wide identity activity, runtime health, recorded model usage, plan distribution, and users with the highest recorded cost. | +| **Users** | An instance-wide, searchable user list. Open a user to review their plan, runtime state, usage, and aggregate storage. Read-and-write administrators can control the runtime and grant or extend Sponsored Confidential. | +| **Runtime fleet** | A cached or refreshed snapshot of running, starting, stopped, failed, unknown, mapped, and unmapped runtimes. Click **Refresh fleet** to reconcile the snapshot before investigating availability. | +| **LLM costs** | Global cost and token totals from the gateway usage ledger for 30, 90, 180, or 365 days. It does not show prompts, sessions, or model-level detail. | +| **Observability** | Recorded cost and token usage for the last 14 days, with a CSV export. The current view does not record evaluation, policy, completion, or response-latency metrics. | +| **Audit log** | The latest 100 identity and access events for the target account. Filter by user, action type, or date, then export the current rows as CSV. | +| **Teams & access** | Microsoft Entra tenant metadata, members, organization roles, teams, access requests, and Agent access records for the target account. The metadata record does not verify or import a directory by itself. | +| **Network egress** | Platform-wide origin and provider bundles for egress-governed sandboxes. These controls do not currently have a per-organization boundary. | + +## Audit log + +Each governance event records the actor, action, target, detail, and time. Current action types cover Microsoft Entra metadata, tenant configuration, teams, roles, access requests, and Agent access records. + +This is not an Agent activity trace or a complete record of Admin mutations. It does not show tool calls, logins, prompts, document edits, messages, files, knowledge graphs, runtime controls, Sponsored Confidential changes, or network-policy changes. Use an Agent's **Analytics** page for its recorded runs. + +## Runtime and user controls + +Open **Users**, select a person, then review the runtime card. A read-and-write administrator can start, stop, or restart the runtime. Stop and restart are blocked during active work, warm-up, active schedules, or an unhealthy state; there is no force-stop control. + +The same user page shows aggregate storage. It does not open or delete the user's stored content. + +Sponsored Confidential changes entitlement for up to 24 months. They do not change the person's Clerk billing subscription. + +## Network egress + +Use **Network egress** to review the origins available to egress-governed sandboxes. A read-and-write administrator can create, edit, or delete provider bundles and delete existing Shared rules. The current panel does not add or edit a standalone Shared rule. + + + A change here applies to every egress-governed user. **Ask** requests user + approval and saves the user's Allow or Deny choice. A global **Deny** gives no + prompt and cannot be overridden. Disabling or deleting a bundle removes only + rules created by that bundle; other global rules and user grants remain. + + +## Troubleshooting + + + + Sign in with the account your deployment operator authorized. An + organization role does not grant panel access. Ask the deployment operator + or [contact Fluso support](mailto:support@premai.io) if the panel role is + missing. + + + The panel distinguishes recorded data from missing telemetry. Retry the + view. If it remains unavailable, check the source service rather than + treating the empty value as zero. + + + Check whether the runtime is busy, warming, unhealthy, already stopped, or + has active schedules or other durable work. Retry after the blocking state + clears. Fluso does not force-stop a runtime from this panel. + + + +## Next + +Read [Privacy](/resources/privacy) for the admin content boundary and [Security](/resources/security) for authentication, isolation, and governance logging. diff --git a/content/docs/developers/api-ref/agents-and-versions.mdx b/content/docs/developers/api-ref/agents-and-versions.mdx index 31db932..fa4905a 100644 --- a/content/docs/developers/api-ref/agents-and-versions.mdx +++ b/content/docs/developers/api-ref/agents-and-versions.mdx @@ -7,7 +7,7 @@ description: Create Agents, read their current immutable configuration, and publ An Agent record points at one immutable configuration through `currentConfigId`. Use that ID as `baseConfigId` when you update the Agent. -Agent-owned work runs in [threads](/developers/api-ref/threads-and-messages) and can start from [schedules](/developers/api-ref/schedules). +Agent-owned work runs in [threads](/developers/api-ref/threads-and-messages) and can start from [schedules](/developers/api-ref/schedules) or [webhooks](/developers/webhooks). ## List Agents @@ -192,7 +192,7 @@ chats keep the configuration they started with. -Deletes the Agent and removes its owned chats, configurations, knowledge, and schedules. +Deletes the Agent and removes its owned chats, configurations, knowledge, schedules, and webhook triggers. ```bash title="Request" curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef" \ @@ -206,4 +206,4 @@ HTTP/1.1 204 No Content ## Next -Start Agent work through [Threads and messages](/developers/api-ref/threads-and-messages), or automate it with [Schedules](/developers/api-ref/schedules). +Start Agent work through [Threads and messages](/developers/api-ref/threads-and-messages), or automate it with [Schedules](/developers/api-ref/schedules) and [Webhooks](/developers/webhooks). diff --git a/content/docs/developers/api-ref/files-and-projects.mdx b/content/docs/developers/api-ref/files-and-projects.mdx index 0905c46..a79d410 100644 --- a/content/docs/developers/api-ref/files-and-projects.mdx +++ b/content/docs/developers/api-ref/files-and-projects.mdx @@ -228,4 +228,4 @@ curl -G "$FLUSO_API/v1/agent/files" \ ## Next -Attach project context to [Agents and versions](/developers/api-ref/agents-and-versions), or create project-bound [Threads and messages](/developers/api-ref/threads-and-messages). +Read [Projects](/features/projects) for the product workflow, attach project context to [Agents and versions](/developers/api-ref/agents-and-versions), or create project-bound [Threads and messages](/developers/api-ref/threads-and-messages). diff --git a/content/docs/developers/meta.json b/content/docs/developers/meta.json index e6f86db..662fbc1 100644 --- a/content/docs/developers/meta.json +++ b/content/docs/developers/meta.json @@ -9,6 +9,7 @@ "project-context", "schedules", "threads-and-contexts", - "user-preferences" + "user-preferences", + "webhooks" ] } diff --git a/content/docs/developers/project-context.mdx b/content/docs/developers/project-context.mdx index 073c77f..068d467 100644 --- a/content/docs/developers/project-context.mdx +++ b/content/docs/developers/project-context.mdx @@ -29,4 +29,4 @@ Use a dedicated project when the Agent should work with one customer's files, on ## Next -See [User preferences](/developers/user-preferences) for the other ordinary-chat layer that saved Agents skip, or [Files and projects](/developers/api-ref/files-and-projects) for project APIs. +See [Projects](/features/projects) for the product workflow, [User preferences](/developers/user-preferences) for the other ordinary-chat layer that saved Agents skip, or [Files and projects](/developers/api-ref/files-and-projects) for project APIs. diff --git a/content/docs/developers/schedules.mdx b/content/docs/developers/schedules.mdx index 24d02b2..687f532 100644 --- a/content/docs/developers/schedules.mdx +++ b/content/docs/developers/schedules.mdx @@ -38,4 +38,4 @@ If a recurring turn is still queued, running, or waiting for approval, Fluso doe ## Next -Use [Schedules](/developers/api-ref/schedules) for the REST endpoints and [Runs](/developers/api-ref/runs) to inspect each accepted turn. +Use [Schedules](/developers/api-ref/schedules) for the REST endpoints, [Webhooks](/developers/webhooks) for event-driven turns, and [Runs](/developers/api-ref/runs) to inspect each accepted turn. diff --git a/content/docs/developers/webhooks.mdx b/content/docs/developers/webhooks.mdx new file mode 100644 index 0000000..f42ce0e --- /dev/null +++ b/content/docs/developers/webhooks.mdx @@ -0,0 +1,120 @@ +--- +title: Webhooks +sidebarTitle: Webhooks +icon: webhook +description: Send authenticated JSON events into an Agent and inspect the resulting thread and delivery receipt. +--- + +An Agent webhook receives JSON from another system and starts a follow-up Agent turn. It is an inbound trigger, not a callback that Fluso sends to another service. + +Choose whether events use a dedicated thread or an existing Agent thread. Each accepted event uses the Agent definition and project attached to that thread. + +## Create a webhook + + + + Open the Agent-name menu and choose **Triggers**. + + + Click **Add trigger**, give it a clear name, and choose an authentication + method. **Header secret** is the safer default. Use a query secret only + when the sending service cannot set a custom header. + + + Select **New thread on first event** to keep these events together in a + dedicated thread, or select an existing non-archived Agent thread. + + + Click **Create trigger**, then copy the webhook secret. Fluso shows the + clear secret only after creation or rotation. The webhook URL remains + available on the trigger row. + + + +## Send an event + +The public delivery URL uses the webhook secret, not your Fluso bearer token. A header-authenticated request looks like this: + +```bash +export FLUSO_WEBHOOK_URL='' +export FLUSO_WEBHOOK_SECRET='' + +curl "$FLUSO_WEBHOOK_URL" \ + -X POST \ + -H 'Content-Type: application/json' \ + -H "X-Fluso-Webhook-Secret: $FLUSO_WEBHOOK_SECRET" \ + -H 'Idempotency-Key: release-ready-2026-09-01' \ + -d '{"event":"release.ready","release":"2026.09.01"}' +``` + +If you chose **Query secret**, send the same value through the `secret` query parameter. Query values can appear in browser, proxy, and server logs, so prefer the header when possible. + +The request must use `application/json`, contain valid JSON, and stay at or below 25,000 bytes. Fluso accepts any JSON shape; define the fields your Agent instructions expect. + +## Read the receipt + +A successful request returns `202 Accepted` with a delivery receipt: + +```json +{ + "id": "", + "receivedAt": "2026-09-01T12:00:00.000Z", + "payloadSummary": "JSON event ยท 54 bytes", + "status": "accepted", + "responseCode": 202, + "requestId": "webhook::", + "threadId": "", + "error": null +} +``` + +`202 Accepted` means the Agent turn was admitted or queued. It does not mean the Agent finished. Open the target thread or the Agent's **Analytics** page to inspect the run. + +If the target thread is already running, the event waits as a follow-up instead of interrupting the current turn. + +## Test and inspect deliveries + +Expand **Test & deliveries** on the trigger row. Edit the sample JSON and click **Send test event**. This is a real Agent turn. + +The trigger shows its latest 20 completed receipts. The list shows accepted or failed status, time, a payload-size summary, and a link to an accepted event's thread. The receipt stores a payload digest and size summary instead of the full JSON body. Idempotency records can remain for 24 hours even when they are no longer in that list. + +The full payload is added to the Agent message and becomes part of the target thread's context and history. Do not send a secret unless the Agent is intended to receive it. + +## Idempotency and retries + +Fluso makes one admission attempt for each delivery. It does not retry a failed request automatically. + +Send one `Idempotency-Key` header when your sender may retry. For 24 hours on that trigger: + +- The same key and payload returns the original receipt without another Agent turn. +- The same key with a different payload returns `409 Conflict`. +- Replaying a failed key returns the same failure; use a new key only when you intend to create a new turn. + +Without an idempotency key, repeated requests create separate Agent turns. + +## Pause, rotate, or delete + +- Turn the trigger switch off to pause it. Requests to a paused trigger return `409`. +- Choose **Rotate secret** if a secret may be exposed. The old secret stops working immediately, and the replacement is shown once. +- Choose **Delete trigger** to remove its URL and delivery history. Later requests to that URL return `404`. + +## Security boundary + +Treat every payload as untrusted input. It becomes thread context, so remove credentials and fields the Agent does not need. A webhook does not bypass the Agent's saved capabilities, tool rules, or approval boundaries. Keep external writes behind approval when an event should prepare work rather than publish it. + +## Common errors + +| Status | Check | +| --- | --- | +| `400` | The body is valid JSON. If present, `Idempotency-Key` appears once and contains 1 to 255 characters. | +| `401` | The header or query secret matches the current secret. | +| `404` | The trigger, Agent, or target thread still exists. | +| `409` | The trigger is enabled, the target is available, and the idempotency key is not conflicting or already in progress. | +| `413` | The raw JSON body is no larger than 25,000 bytes. | +| `415` | `Content-Type` is `application/json`. | +| `429` | The sender's IP rate limit or the Agent owner's usage limit has been reached. Honor `Retry-After` when it is present. | +| `502` or `503` | The Agent service and runtime are available. A repeated failed key returns the recorded failure and does not start another attempt; use a new key only when you intend one. | + +## Next + +Use [Runs](/developers/api-ref/runs) to inspect accepted turns, [Threads and contexts](/developers/threads-and-contexts) to understand the target thread, and [Schedules](/developers/schedules) for time-based triggers. diff --git a/content/docs/features/imports.mdx b/content/docs/features/imports.mdx index 29d4400..d3dcfd3 100644 --- a/content/docs/features/imports.mdx +++ b/content/docs/features/imports.mdx @@ -142,4 +142,4 @@ After importing, open one of the new projects and ask: > *"Summarise this project. What is decided, what is still unclear, and what should I do next?"* -For project habits after import, see [Going deeper](/going-deeper#use-projects-properly). +For project habits after import, see [Projects](/features/projects) and [Going deeper](/going-deeper#use-projects-properly). diff --git a/content/docs/features/mcp.mdx b/content/docs/features/mcp.mdx index 16cd1a0..de323ce 100644 --- a/content/docs/features/mcp.mdx +++ b/content/docs/features/mcp.mdx @@ -45,8 +45,9 @@ Switch to the **Custom server** tab and paste the endpoint URL. Use the exact Streamable HTTP endpoint. It must be reachable from Fluso over public HTTPS; `localhost`, private network addresses, and `stdio` commands - are not connection URLs. The workspace or organization network-egress - policy, plus any provider policy applied to that origin, must allow it. + are not connection URLs. The workspace or organization + [network-egress policy](/admin-panel#network-egress), plus any provider + policy applied to that origin, must allow it. diff --git a/content/docs/features/memory.mdx b/content/docs/features/memory.mdx index 78a37a8..23693fc 100644 --- a/content/docs/features/memory.mdx +++ b/content/docs/features/memory.mdx @@ -66,7 +66,7 @@ One-off task details stay out of the durable files too. They live in working mem ## Reading and correcting it -Memory is yours to read. Ask *"what do you remember about me?"* or *"what's in this project's context?"* and Fluso reads the files back to you. `preferences.md` and each project's `context.md` sit in your workspace as plain markdown you can open yourself. +Memory is yours to read. Ask *"what do you remember about me?"* or *"what's in this project's context?"* and Fluso reads it back to you. Project context is stored in `context.md`, which is hidden from the project file explorer. Corrections work the same way: *"forget my old timezone"*, *"that decision was reversed, update the context"*. If you want a clean slate for a project's working memory, ask Fluso to reset it. diff --git a/content/docs/features/meta.json b/content/docs/features/meta.json index 470bd71..fb2774e 100644 --- a/content/docs/features/meta.json +++ b/content/docs/features/meta.json @@ -6,6 +6,7 @@ "confidential", "imports", "memory", + "projects", "skills", "tasks", "!connectors" diff --git a/content/docs/features/projects.mdx b/content/docs/features/projects.mdx new file mode 100644 index 0000000..c68d051 --- /dev/null +++ b/content/docs/features/projects.mdx @@ -0,0 +1,61 @@ +--- +title: Projects +sidebarTitle: Projects +icon: folder-kanban +description: Keep related chats, files, instructions, and memory together in one workspace. +--- + +Projects give one body of work its own scope. A project keeps its chats, files, instructions, context, and working memory together, so work for one customer or product does not spill into another. + +Use **Home** for general work. Create a separate project when a customer, product area, or deliverable needs its own files and history. + +## Create a project + +Open **Projects** from the left sidebar, then click **New Project**. + +| Field | What it does | +| --- | --- | +| Name | Identifies the project in the sidebar and project list. | +| Description | Adds a short summary to the project list and project header. | +| Instructions | Sets standing guidance for ordinary chats in this project. | + +Start with instructions that will still be true next week: + +> *"Use the launch brief as the source of truth. Keep decision notes in plain text and call out missing owners."* + +## Work with project files + +Open a project to see its file explorer. From there, you can: + +- Upload files or drag them into a folder. +- Create folders and search the project workspace. +- Preview supported files and download results. +- Export the whole project as a ZIP archive. +- Start a new chat already scoped to the project. + +Files created in project chats stay in the same workspace. That makes the project a useful home for source material, drafts, and finished deliverables. + +[Tasks](/features/tasks#tasks-and-projects) can also belong to a project, keeping their follow-up chat in the same scope. + +## Keep context in the right place + +Project instructions guide ordinary project chats. Durable notes and decisions live in `context.md`, while working memory keeps short summaries of recent work. The file is hidden from the project explorer; say *"add this to project context"* in a project chat when you want Fluso to update it. + + + Saved Agent threads use the Agent's own instructions instead of project + instructions or `context.md`. They can still use the configured project's + files and working-memory summaries. See [Project + context](/developers/project-context) for this boundary. + + +Use one project per scope that should stay separate. For example, keep Acme support work in an Acme project and the Q3 launch in a Q3 Launch project. Start a new chat inside the same project when the topic changes but the files and background should remain available. + +## Organize projects + +Use the project's sidebar actions menu to pin, archive, label, recolor, or change its icon. Use the menu on the Projects page to export or delete it. **Home** is the default workspace and cannot be deleted. + +If you already have useful context in ChatGPT, Claude, or another agent, use [Imports](/features/imports) to create projects and files from an export. + +## Next + +Read [Memory](/features/memory) for the context carried between chats, or [Files and projects](/developers/api-ref/files-and-projects) for the API. diff --git a/content/docs/going-deeper.mdx b/content/docs/going-deeper.mdx index 562bfaa..183edb1 100644 --- a/content/docs/going-deeper.mdx +++ b/content/docs/going-deeper.mdx @@ -27,11 +27,11 @@ A few patterns worth practising. ## Use projects, properly -Projects are folders for context. Most people create one and forget. The better habit: +[Projects](/features/projects) are folders for context. Most people create one and forget. The better habit: A project per major area of work. Acme Corp, Q3 Launch, Board Reporting, Personal. When you're inside a project, Fluso scopes its memory and search to that project's content. Asking "what's the status?" inside the Acme project gets the Acme answer; same prompt outside any project gets a generic everything-bag. -Drop a `context.md` into the project's workspace if your context is non-obvious. The simplest version: +Add stable project context when the background is non-obvious. The simplest version: ```markdown # Acme Corp @@ -43,7 +43,7 @@ Drop a `context.md` into the project's workspace if your context is non-obvious. - Sensitive: don't reference our internal pricing model in emails to them ``` -Fluso reads it before answering anything inside the project. The cost is two minutes; the payoff shows up in every reply for months. +Paste this into a project chat and say *"add this to project context"*. Fluso stores it in the hidden `context.md` file and reads it before answering ordinary chats inside the project. If you are bringing work over from ChatGPT, Claude, or another agent, use [Imports](/features/imports) to turn that context into Fluso projects and files. @@ -128,7 +128,7 @@ Team plans add shared context. The patterns that matter: **Shared knowledge graph** for the team. Decisions made in any team member's meetings are visible to everyone (within the shared project). Useful for executive teams; less useful for projects with strict need-to-know. -**Admin visibility, not content access.** The current browser admin covers local identity and access records. Connected-app inventory, seat controls, and durable audit require a server-side Enterprise integration. The admin UI does not expose messages, files, or knowledge graphs. +**Admin visibility, not content access.** The current [Admin panel](/admin-panel) covers identity and access records, recorded usage, runtime status, and network policy. Connected-app inventory, seat controls, and a complete organization-wide audit require their owning Enterprise integrations. The admin UI does not expose messages, files, or knowledge graphs. ## Things people miss diff --git a/content/docs/meta.json b/content/docs/meta.json index 4954c05..1fa3a35 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,6 +1,8 @@ { "pages": [ "index", + "---Administration---", + "admin-panel", "---Agents (Beta)---", "...developers", "---App setup---", diff --git a/content/docs/resources/privacy.mdx b/content/docs/resources/privacy.mdx index 84fe617..732aa6a 100644 --- a/content/docs/resources/privacy.mdx +++ b/content/docs/resources/privacy.mdx @@ -102,7 +102,7 @@ The graph is the thing most worth understanding here, because it's the thing tha ## On Team plans -The current admin can: +The current [Admin panel](/admin-panel) can: - Store team membership, workspace roles, Agent access policies, access requests, and Microsoft Entra tenant metadata in the authenticated account's backend governance record. - Review the identity and access changes recorded there. diff --git a/content/docs/resources/security.mdx b/content/docs/resources/security.mdx index 963477f..b00ebb1 100644 --- a/content/docs/resources/security.mdx +++ b/content/docs/resources/security.mdx @@ -35,7 +35,7 @@ OAuth tokens are encrypted before persistence and decrypted only by the backend **Secret delivery.** Hosted runtime secrets use a one-time bootstrap payload: Docker receives it over stdin, while ECS uses an authenticated one-shot HTTP handoff. The payload is kept out of mounted files and the final process environment. -**Governance audit logging.** Authenticated identity and access changes are stored in the backend governance record and shown in the admin audit view. This log covers the governance actions shown there; account-lifecycle, OAuth, and deletion auditing require their owning server integrations. Governance records do not contain the content of your work. +**Governance audit logging.** Authenticated identity and access changes are stored in the backend governance record and shown in the [Admin audit log](/admin-panel#audit-log). This log covers the governance actions shown there; account-lifecycle, OAuth, and deletion auditing require their owning server integrations. Governance records do not contain the content of your work. ## Account security