Slack, web conversations, routines and native review/fix jobs share the capability catalog, current authority checks, run ledger and operation receipts. Runs, charts and saved reports open inside the conversation inspector. Consolidates duplicate regression suites and documentation while retaining the product contracts, native recovery evidence and migration baseline transition. Validation: all eleven exact-input local checks pass, including 1,216 integration examples (25 pending VM cases), 2,105 doctests, 315 unit examples, 16 CLI examples, 1,041 UI tests and 172 browser tests (one skip). Separate native/KVM acceptance is recorded in the review. The exact Linux AMD64 image was built locally on this Mac with OrbStack/Rosetta. |
History
|
|
|---|---|---|
| .. | ||
| chart-fixtures/query-failure | ||
| agent-manifest.json | ||
| README.md | ||
Slack agent installation
Install or reconnect Slack from the project's integrations page or onboarding.
The initiating Monoscope user must be an active project admin and stay signed in
as the same user when Slack returns to /slack/oauth/callback.
Installation requests expire after 15 minutes and can be used once. If the
exchange fails or the request expires, start again from Monoscope.
Do not construct an OAuth URL with a project ID as state; the callback rejects it.
Activate the Slack routine
- Open Agents → Routines in the connected project.
- Add Slack investigation. You need project edit or admin permission.
- Open the routine to review or change its instructions.
- Mention Monoscope, send a direct message, or use
/monoscopein Slack. - Open View runs and artifacts in the reply to inspect the result.
Each request uses the linked member's current project access. The routine also checks the access of the member who activated it. If that member loses edit permission, another editor must resume the routine. New installations use Autonomous: requested project changes use the linked member's current role and the shared action ledger. Existing Observe installations keep their policy until an editor changes it. Channel replies cannot use private administrative evidence.
The routine stores the request, requester, instructions, status, results, and artifacts. Each retry keeps a separate attempt. Changes to instructions apply to future runs. Past runs keep their own instructions and artifacts. Run links open the conversation with its run details beside it. Within a conversation, runs and artifacts open in the same detail panel without clearing your draft. On narrow screens, close the panel or press Escape to return to the conversation.
For optional review, choose Review selected actions under Execution policy in the routine's conversation. Select the action classes and required reviewer, then save. Other actions stay automatic. Waiting actions appear in the same run panel and Slack notice. Approval resumes the original request; rejection, expiry, or withdrawn access prevents the action. Autonomous does not require these votes.
Pause the routine to stop current and future investigations. Use Stop active runs to stop current work while keeping the routine enabled for future requests. If the routine is absent or paused, Slack returns private activation instructions. Notification delivery remains connected.
Enable incident investigations in a channel
- Link your Monoscope account and choose a channel that receives incident alerts.
- As a project editor or admin, run
/monoscope incidents onin that channel. - Follow the returned link to review the channel routine, instructions, and run history.
- To allow automatic project changes, explicitly change its policy to Autonomous.
Each channel has its own installation and owner. New incident routines start in Observe. They investigate recorded alerts automatically and post a short summary in the incident thread, with a link to the complete retained result. A recorded recovery or explicit resolution triggers a closing report. Missing errors or measurements do not establish recovery.
Run /monoscope incidents off to pause this channel's incident routine. The
existing routine controls also pause work, stop active runs, and change policy.
The worker checks current access during execution and before report delivery.
Retries reuse retained results and delivery identities. A lost Slack
acknowledgement is reconciled before another reply can be sent.
Activate pull request reviews
- Open Agents → Routines in the project.
- Add Production impact review.
- Open the repository settings and enable its automatic pull request reviews.
- Choose Links only or Aggregates and links for evidence sent to GitHub.
Both the routine and repository must permit a review. Each review retains its run, instructions, evidence, and artifact in Monoscope. The GitHub comment links to that run. Use the repository's review history to retry a review. A retry keeps earlier attempts and artifacts.
Activate issue enrichment
- Open Agents → Routines in the project.
- Add Issue enrichment to permit automatic issue metadata updates.
- Open the routine to change its instructions or pause future work.
Each eligible new issue gets a run in the issue's conversation. The run retains its assessment, recommended action, severity, instructions, and result artifact. Failed work keeps its attempt. A retry creates another attempt. Duplicate job deliveries do not repeat completed work. Pausing the routine prevents later model results from changing issue metadata.
Install the Slack app
The OAuth request includes assistant:write alongside the existing scopes. The
callback stores the scopes returned by Slack. Installations with missing or
unknown assistant:write/chat:write grants receive a private reconnect prompt
before native investigation work. Existing credentials, webhook destinations,
and notification paths stay configured. The integrations page also offers the
existing admin-authorized reconnect flow. Stored grants establish permissions,
not live Agent availability or acceptance.
agent-manifest.json is the reviewable app configuration
template. Replace every https://YOUR_MONOSCOPE_HOST with the deployed origin,
then compare it with the current app manifest before applying it in the selected
sandbox. It declares agent_view without static prompts and includes commands, signed
callback routes, event subscriptions, and incoming webhooks.
Static prompts are omitted so the app can update suggestions from project state when
the Messages tab opens or assistant context changes. Existing apps must also remove
static prompts in their Slack configuration; Slack rejects dynamic updates while
static prompts are configured.
It retains the existing notification scopes. Preserve unrelated live app settings
when merging the template. The Agent declaration is required in addition to OAuth
grants; see Slack's Agent guide.
Slack documents migration from assistant_view to agent_view as irreversible.
This repository change does not apply that migration. Live manifest validation, plan availability, and workspace acceptance
remain rollout gates. See the manifest reference.
The 1 November live configuration audit records the existing app's configuration gaps and the remaining acceptance sequence. It does not apply the template or establish live branch acceptance.
Opening the Agent's Messages tab also starts personal linking for an unlinked user. Repeat opens suppress another prompt while a successfully delivered, unconsumed link remains valid in that conversation. After expiry, a new visit can issue a new link. Already-linked users and visits to other tabs receive no onboarding prompt. App Home visits do not start investigations. A rejected prompt leaves the receipt pending; delivery is recorded only after Slack acknowledges it.
Personal Slack search consent
After linking your identity, use /monoscope search connect for a private link
to Slack's user authorization page. The connection uses the registered
/slack/oauth/callback, a single-use state, and S256 PKCE. The returned workspace
and Slack user must match the linked account and current project membership.
This flow does not replace the project's bot credentials or alert destination.
The manifest's user scopes contain read access only. Slack currently allows MCP for internal or Marketplace apps; enable MCP in the app's Agents → Slack MCP Server settings before live acceptance. These repository changes do not apply live app settings. See Slack's MCP requirements.
Use /monoscope search disconnect to remove your personal grants and pending
consent for the current project. Disconnect also invalidates an exchange already
in flight. Access and refresh tokens use the shared authenticated encryption
helper. Tokens are unavailable after membership loss or workspace replacement. Expired
access tokens require a successful refresh before use. Rotating grants retain
their refresh token and expiry together.
Signed tokens_revoked events remove the named users' grants and pending consent
in that workspace. The receipt and cleanup commit together, so duplicate delivery
or a delayed worker cannot remove a later reconnection. The same worker recovers a
failed intake cleanup. The manifest includes the required event subscription.
The credential resolver refreshes rotating tokens before expiry or on their next use after expiry. Code exchange and refresh share one OAuth client. Concurrent callers share a durable claim; HTTP runs outside database transactions. A definite rate limit leaves the refresh token available for retry. An uncertain exchange is not replayed. If its access token expires, the user must reconnect. Disconnect, membership loss, and workspace replacement prevent an in-flight response from restoring access; a later reconnection wins over an older refresh response.
The agent discovers Slack search, channel history, and thread reads through the shared tool catalog. Each read uses the linked requester's personal grant and checks the provider's current tool schema. Provider write tools are excluded. Channel requests can read their own authorized destination; personal workspace search requires a personal conversation. Current Slack membership is checked before and after restricted reads.
Retained evidence carries its audience into later model turns, saved documents, and run history. A private read cannot authorize publication into a shared Slack channel or project wiki. Consent, refresh, disconnect, revocation, MCP reads, and audience containment have integration coverage. Actual app eligibility, live provider schemas, Slack Connect, and controlled workspace acceptance remain rollout gates.
Link a Slack identity
To link a personal account, mention Monoscope or message it directly in Slack. An unlinked user receives an ephemeral link addressed to that Slack user. Sign in to Monoscope, choose a project, and submit the form. The project list only includes current memberships connected to the requesting Slack workspace. The link expires after 15 minutes and works once. This follows Slack's account-binding flow.
A Slack identity cannot be reassigned to a different Monoscope account through
this flow. A new link can change the same user's default project. Existing
investigation threads retain their original project. Signed-event investigations
recheck access before model calls, before and after tools, and before delivery.
Slash commands use the linked user's current default project. /monoscope-here
requires project-admin permission and changes only that project's notification
channel. Moving the channel clears the old channel-bound incoming webhook so
notifications use the bot API. Unlinked or revoked users receive a private prompt
to link or check their access.
Dashboard modals retain their project and requesting Slack user. Each selection,
preview, and share rechecks current membership. Widget definitions come from the
project's saved dashboard or its known template; modal metadata carries no file
path or chart URL. A changed widget requires a new selection. Modals opened before
this metadata upgrade must be reopened with /dashboard. Native Agent lifecycle
and the remaining acceptance gates still apply before rollout.
Native app_context_changed events retain navigation hints separately for each
workspace, app conversation, and Slack user. Newer empty context clears old hints;
delayed events cannot restore them. Context does not grant access, bind a project,
or start an investigation. Using these hints as scoped investigation evidence
remains future work.
agent_session_title_changed updates the stored title of an existing project
thread only for a linked current member. Its workspace must match the signed
envelope. Delayed title events cannot replace newer titles, and title updates do
not alter cancellation state. See Slack's title event.
Threaded follow-ups retain user/assistant roles and complete model answers. Previous conversation text is not added to the system prompt. The model receives the latest 200 stored messages in chronological order. Slack backfill ends before the triggering event, using the documented reply timestamp boundary. Only messages attributed to this app become assistant history. Backfill follows all returned cursors and rechecks access before and after each page. A failed or incomplete fetch stops the investigation before any model call and leaves the receipt pending for retry. The worker stores model and tool checkpoints. Retries resume the stored turn and reconcile reserved replies before another publication.
Signed-event investigations set the native session to processing before work
and attempt to return it to active on completion or failure, using
agents.sessions.setStatus.
A rejected startup status is logged and the investigation continues without
native processing state. Failed status cleanup is logged without replaying a
completed answer.
Signed agent_session_stopped events persist a cancellation cutoff for an existing
project thread. Only a linked, current project member can stop its investigation.
Running work checks that cutoff at access boundaries and every half second while
waiting for model/tool work. Cancellation attempts to clear the processing status
and posts a threaded confirmation. Later questions can start new work. Subscribe
to the stop event
before enabling this flow. Workers serialize human messages within each workspace,
channel, and thread. A competing worker leaves its receipt pending for retry;
other threads can proceed. The lock covers status cleanup and receipt completion,
and a lost lock connection interrupts blocked work. Durable status and delivery
reconciliation remain rollout gates.
Set SLACK_SIGNING_SECRET and SLACK_APP_ID for the Slack app that posts incident alerts.
The signing secret verifies incoming requests. The app ID verifies the author of a captured message.
Events, slash commands, actions, and external-option requests verify the original body
before decoding. Missing or invalid signatures return 401; an empty signing secret
makes these endpoints return 503. An empty app ID prevents root capture.
Messages carry monoscope_incident_root metadata with the saved root ID.
Slack does not require registration before sending custom metadata. Optional
schemas use the top-level events manifest field and require org-wide deployment.
The workspace template omits these declarations. See
Slack message metadata.
Configure the Events API callback as /slack/events on the application host.
Subscribe to message events for the selected channels and grant the corresponding history scopes.
The app must receive its own posted message, including metadata, before an accepted webhook root can release queued replies.
Slack documents the Events API as one way to obtain a webhook message timestamp. See incoming webhooks.
The application checks the saved signed event's author app, workspace, channel, root ID, and timestamp. The receiving app ID alone is insufficient. A human-authored message cannot claim a root by copying its metadata. A root timestamp cannot be replaced by a conflicting observation.
These files describe configuration; they do not apply it to a live app. Controlled workspace acceptance and the remaining Slack-agent plan gates are required before rollout.
Error patterns remain open when error observations stop. Quiet counters do not establish recovery or trigger automatic resolution. An operator can resolve an error explicitly. Monitor recovery still requires a measured value that passes its recovery condition; missing or failed evaluations show DATA UNAVAILABLE in existing incident threads and retain the last verified reading.
Investigation progress reconciliation
Progress messages carry monoscope_investigation_progress metadata with a
publication_id string. The app must receive its own message events with the
complete metadata payload, as incident-root reconciliation requires. Verify this
in the selected sandbox. This worker handles ordinary message events; it does
not handle metadata-only event subscriptions. See
Slack message metadata.
A progress publication is reserved before sending. If its acknowledgement is missing, Monoscope retains the reservation instead of posting another checklist. A stored signed message observation must match the configured receiving app, message author app, workspace, channel, thread and publication ID. A matching observation supplies the timestamp and refreshes the latest activity for that turn, including after the answer has finished. The refresh checks the original requester's current access and uses the investigation lock to serialize updates.
Signed-event investigations store each reply batch and reserve each part before publication. The worker also reconciles reserved replies with paged thread history. It checks the app and publication ID before it records delivery. A missing observation or inaccessible history leaves the reservation pending. A timeout does not prove that Slack rejected a message. Check actual scopes, metadata delivery, and rate limits in the sandbox before rollout.
Use the message shortcut Ask Monoscope about this to investigate a selected
message in its original thread. For a reply, Monoscope continues the existing
thread. The shortcut uses the clicking member's linked project and current access;
the selected author does not grant authority. Message text and blocks are quoted
as untrusted evidence. Signed deliveries enter the same receipt queue, run,
checkpoint, and publication path as mentions. Repeating a delivery does not start
another investigation. Unlinked and revoked users receive private account-link
guidance. The template declares callback ID monoscope-investigate-message on
the existing /actions/slack interactivity endpoint; apply it to the selected app
before live acceptance.