Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-inbox-fact-indicator.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Inbox machine transcripts now become knowledge, and the "πŸ“š Fact" button is gone.** A finished machine transcription (whisper, Gemini or Deepgram) is written into the item's Knowledge fact, fenced as untrusted data and marked `attr_<x>_content: machine` with `attr_transcript_provider`, so knowledge search, nous and agents see the words instead of a pending placeholder; later syncs keep it until the source produces its own text, which then replaces it. The action row no longer has a "πŸ“š Fact" button: a status pill (*Pending text*, *In knowledge (machine text)*, *In knowledge*) shows what the fact holds, and an *open in Knowledge* link in the metadata line opens it.
15 changes: 15 additions & 0 deletions dashboard/test/inbox-item.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,21 @@ test('pending item explains that Plaud has no text yet and never shows the MCP e
assert.doesNotMatch(html, /<audio/, 'no audio element (and no URL) before the owner clicks play');
});

test('the Knowledge fact is a status pill and a metadata link, never a row button', () => {
const ctx = makeContext('owner');
const html = vm.runInContext('inboxItemHtml(' + JSON.stringify(Object.assign({}, pendingItem, { fact_state: 'pending' })) + ')', ctx);
assert.doesNotMatch(html, /πŸ“š Fact/);
assert.doesNotMatch(html, /<button[^>]*data-action="inboxOpenFact"/, 'no Fact button');
assert.match(html, /<div class="muted-xs">[^]*<a href="#" class="inbox-fact-link" data-action="inboxOpenFact" data-prevent="1" data-arg0="plaud-plaud-f_1" data-arg1="personal"[^>]*>open in Knowledge<\/a><\/div>/);
assert.match(html, /<span class="kc-pill" role="status" data-status="not loaded" data-fact-state="pending"[^>]*>Pending text<\/span>/);
const machine = vm.runInContext('inboxItemHtml(' + JSON.stringify(Object.assign({}, pendingItem, { pending: false, fact_state: 'machine' })) + ')', ctx);
assert.match(machine, /data-fact-state="machine"[^>]*>In knowledge \(machine text\)<\/span>/);
const ready = vm.runInContext('inboxItemHtml(' + JSON.stringify(Object.assign({}, readyItem, { fact_slug: 'plaud-plaud-f_2', fact_state: 'ready' })) + ')', ctx);
assert.match(ready, /data-fact-state="ready"[^>]*>In knowledge<\/span>/);
const live = vm.runInContext('inboxItemHtml(' + JSON.stringify(readyItem) + ')', ctx);
assert.doesNotMatch(live, /inbox-fact-link|data-fact-state/, 'no fact yet: no pill, no link');
});

test('summary renders inline and collapses past the threshold with a more toggle', () => {
const ctx = makeContext('owner');
let html = vm.runInContext('inboxItemHtml(' + JSON.stringify(readyItem) + ')', ctx);
Expand Down
2 changes: 1 addition & 1 deletion src/docs/design/email-inbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ reads the vendor directly, with `PreferDirect` merging the two
emits pages on an interval. Email is push. So the email source is a native
`inbox.Source` over its own on-disk spool, and it optionally writes a Knowledge
fact per message through the same `FactWriter` slug scheme
(`src/pkg/knowledge/connector/factwriter.go:34`) so "πŸ“š Fact" keeps working.
(`src/pkg/knowledge/connector/factwriter.go:34`) so the Inbox's *open in Knowledge* link keeps working.
`SetSources` already lets a source appear without restart
(`src/pkg/inbox/service.go:70-78`).

Expand Down
19 changes: 13 additions & 6 deletions src/docs/inbox-transcription.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,8 +172,9 @@ Transcription is spoke-local. Nothing about it is shared or central:
account. No hive pays for, or sees, another hive's transcriptions.
- **Your data volume.** The transcript is written only to this hive's data
volume, under `connector-state/transcripts/<source>/<id>.json` (mode
`0600`, written atomically). It is not sent to the hub, to other spokes, or
back to the recording's source.
`0600`, written atomically), and into the item's Knowledge fact on the
same volume. It is not sent to the hub, to other spokes, or back to the
recording's source.
- **Your budget.** Monthly minutes, a daily item cap and size/duration limits
are configured per hive and checked before any audio is uploaded. With
whisper the minutes budget limits CPU time on the hive, not money.
Expand Down Expand Up @@ -350,10 +351,16 @@ and the boot log line `inbox transcription enabled` name the hosts. See

## Upstream text wins

The machine transcript is a fallback. If the source later produces its own
summary or transcript (for example the owner runs transcription in the Plaud
app), the Inbox shows the source's text and the machine transcript is no
longer used. If the source is unreachable, the stored machine transcript
The machine transcript is a fallback. When a run finishes, the hive also
writes the transcript into the item's Knowledge fact (marked
`attr_<x>_content: machine` with `attr_transcript_provider`), so knowledge
search, nous and agents see the text, not only the Inbox; see
[What knowledge an Inbox item becomes](inbox-voice-sources.md#what-knowledge-an-inbox-item-becomes).
Later syncs that still find no text upstream keep that fact as it is. If
the source later produces its own summary or transcript (for example the
owner runs transcription in the Plaud app), the next sync replaces the
machine text in the fact, the Inbox shows the source's text and the machine
transcript is no longer used. If the source is unreachable, the stored machine transcript
still serves the item's content.

## Cost
Expand Down
76 changes: 75 additions & 1 deletion src/docs/inbox-voice-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,9 @@ see the issue linked from the changelog entry.
`<channel>:<message ts>` in `attr_slack_huddle_recording_id`; for Otter the conversation id in `attr_otter_recording_id`; for Granola the note id in `attr_granola_recording_id`; for Limitless the lifelog id in `attr_limitless_recording_id`; for Fathom the recording id in `attr_fathom_recording_id`; for Fireflies the transcript id in `attr_fireflies_recording_id`). When the source is connected the Inbox lists
recordings directly from it, so an item may appear before the sync has
written its Knowledge fact; the Inbox only tracks what you did with it.
"πŸ“š Fact" opens the fact in Knowledge once that fact exists.
Once that fact exists, the item's metadata line carries an *open in
Knowledge* link, and a status pill says what the fact holds (see
[What knowledge an Inbox item becomes](#what-knowledge-an-inbox-item-becomes)).
- **Destination** β€” where an item goes:
- **β†’ RFC** (`spek_rfc`): the hive hands the item to a spoke agent with
a kick prompt: `inbox.spek.agent` if set, otherwise the first enabled,
Expand Down Expand Up @@ -126,6 +128,78 @@ transcription/summary in the Plaud app to fill it. Facts written before this
behaviour, whose body carries the "not available" line, are refreshed the
same way.

## What knowledge an Inbox item becomes

Every Inbox item is backed by one Knowledge fact, written by its connector's
sync under `<knowledge base>/connectors/<layer>/<type>-<connector>-<id>.md`.
That fact, not the Inbox view, is what knowledge search, nous and agents
read. Its `attr_<x>_content` key (`attr_plaud_content` for Plaud,
`attr_meeting_content` for the meeting connectors) records which of three
shapes it has, and the Inbox shows it as a status pill (not a button):

- **Audio only (pending)**, pill *Pending text*. The source has no summary
and no transcript. The fact holds metadata only: the title, the
recording time, the duration, the device highlights when there are any,
and the pending note; it is marked `attr_<x>_content: pending` and the
connector re-reads it on every sync. A Plaud example:

```markdown
---
title: Drive home
type: reference
layer: personal
status: active
tags: [connector, plaud, plaud]
source: plaud
connector: plaud
source_id: rec-2
source_path: Plaud
attr_duration_ms: 61000
attr_plaud_content: pending
attr_plaud_file_id: rec-2
synthesized: 2026-11-11T18:00:00Z
synced_at: 2026-11-11T20:00:00Z
---

# Drive home

- **Recorded:** 2026-11-11T18:00:00Z
- **Duration:** 1m1s

_Plaud has not transcribed this recording yet. Open it in the Plaud app to run transcription and the AI summary; the hive re-checks it on every sync until text arrives._

## Highlights

Moments flagged with the device button:

- 05:03
```

Knowledge search finds the title, never the words that were spoken.
- **After machine transcription**, pill *In knowledge (machine text)*. When
a [machine transcription](inbox-transcription.md) finishes, the hive
writes the transcript into the same fact: `attr_<x>_content: machine`,
`attr_transcript_provider: <provider>/<model>` (for example
`whisper/base.en`), `attr_transcript_language` and `attr_transcribed_at`
are set, the pending note is replaced by a `## Transcript (machine:
<provider>/<model>)` section ahead of the highlights, and every other
attribute, the metadata bullets and the highlights stay. The transcript
is spoken by third parties, so it is fenced in the same
`<untrusted-inbox-data source=".." id=".." nonce="..">` envelope the
Inbox uses when it hands item text to an agent. A transcript that
finished before the fact existed is written the next time the Inbox is
listed. The connector keeps re-reading the recording, and a sync that
still finds no text upstream leaves the machine fact alone; it is never
reset to pending.
- **After upstream transcription**, pill *In knowledge*. When the source
produces its own summary or transcript (the owner runs transcription in
the Plaud app, the meeting platform finishes processing), the next sync
rewrites the fact with the source's text and `attr_<x>_content: ready`,
replacing any machine transcript.

An item listed straight from a connected source before its first sync has
no fact yet, so it shows no pill and no link.

## Meeting recordings (Zoom, Teams)

Zoom and Teams items look like Plaud items: the title is the meeting topic,
Expand Down
17 changes: 14 additions & 3 deletions src/pkg/dashboard/static-src/js/inbox.js
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,16 @@
function inboxTranscriptionHtml(it, key) {
const st = it.transcription;
const src = escapeHtml(it.source), id = escapeHtml(it.id);
let html = '';
// What the item's Knowledge fact holds, as a status pill (not a
// control): the source's own text, this hive's machine transcript, or
// metadata only while no text exists yet.
const factStates = {
ready: { label: 'In knowledge', status: 'ok', title: 'Stored as a Knowledge fact with the source\'s own text; knowledge search and agents see it.' },
machine: { label: 'In knowledge (machine text)', status: 'ok', title: 'Stored as a Knowledge fact with this hive\'s machine transcript; the source\'s own text replaces it when it exists.' },
pending: { label: 'Pending text', status: 'not loaded', title: 'Stored as a Knowledge fact with metadata only (title, date, duration, highlights); no text yet, so knowledge search finds no words.' },
};
const fs = factStates[it.fact_state] || factStates.ready;
let html = it.fact_slug ? '<span class="kc-pill" role="status" data-status="' + fs.status + '" data-fact-state="' + escapeHtml(it.fact_state || 'ready') + '" title="' + escapeHtml(fs.title) + '">' + escapeHtml(fs.label) + '</span>' : '';
if (st && st.status) {
const busy = st.status === 'queued' || st.status === 'running';
const pill = st.status === 'done' ? 'ok' : (st.status === 'failed' ? 'error' : (busy ? 'syncing' : ''));
Expand Down Expand Up @@ -289,7 +298,10 @@
const checked = _inboxSelected.has(key) ? ' checked' : '';
const when = it.recorded_at && !String(it.recorded_at).startsWith('0001') ? relativeTimeShort(it.recorded_at) : '';
const dur = inboxFmtDuration(it.duration_ms);
const meta = [escapeHtml(it.source), when ? 'recorded ' + when : '', dur].filter(Boolean).join(' Β· ');
// The backing Knowledge fact is a plain link in the metadata line, not
// an action: it only opens the fact.
const factLink = it.fact_slug ? '<a href="#" class="inbox-fact-link" data-action="inboxOpenFact" data-prevent="1" data-arg0="' + escapeHtml(it.fact_slug) + '" data-arg1="' + escapeHtml(it.layer || '') + '" title="Open this item\'s Knowledge fact">open in Knowledge</a>' : '';
const meta = [escapeHtml(it.source), when ? 'recorded ' + when : '', dur, factLink].filter(Boolean).join(' Β· ');
const routes = it.routes || {};
let pills = '';
for (const d of Object.keys(routes)) pills += inboxStatePill(d, routes[d]) + ' ';
Expand All @@ -307,7 +319,6 @@
else actions += '<button type="button" class="hv-btn btn-secondary btn-sm" data-action="inboxUndismiss" data-arg0="' + src + '" data-arg1="' + id + '">Back to inbox</button>';
}
actions += '<button type="button" class="hv-btn btn-secondary btn-sm" data-action="inboxShare" data-arg0="' + src + '" data-arg1="' + id + '" title="Share a link to this item in the Inbox (not the recording)">πŸ”— Share</button>';
if (it.fact_slug) actions += '<button type="button" class="hv-btn btn-secondary btn-sm" data-action="inboxOpenFact" data-arg0="' + escapeHtml(it.fact_slug) + '" data-arg1="' + escapeHtml(it.layer || '') + '" title="This item is already a Knowledge fact">πŸ“š Fact</button>';
return '<div class="kb-fact-item inbox-item" data-inbox-key="' + escapeHtml(key) + '">' +
(owner ? '<label class="inbox-check"><input type="checkbox" data-change-action="inboxToggleSelect" data-arg0="' + src + '" data-arg1="' + id + '"' + checked + ' aria-label="Select ' + escapeHtml(it.title) + '"></label>' : '') +
'<div class="inbox-icon" title="' + src + '">' + inboxSourceIcon(it.source) + '</div>' +
Expand Down
17 changes: 14 additions & 3 deletions src/pkg/dashboard/static/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -47522,7 +47522,16 @@ <h3 class="modal-h">How Agents Use Knowledge (Priming)</h3>
function inboxTranscriptionHtml(it, key) {
const st = it.transcription;
const src = escapeHtml(it.source), id = escapeHtml(it.id);
let html = '';
// What the item's Knowledge fact holds, as a status pill (not a
// control): the source's own text, this hive's machine transcript, or
// metadata only while no text exists yet.
const factStates = {
ready: { label: 'In knowledge', status: 'ok', title: 'Stored as a Knowledge fact with the source\'s own text; knowledge search and agents see it.' },
machine: { label: 'In knowledge (machine text)', status: 'ok', title: 'Stored as a Knowledge fact with this hive\'s machine transcript; the source\'s own text replaces it when it exists.' },
pending: { label: 'Pending text', status: 'not loaded', title: 'Stored as a Knowledge fact with metadata only (title, date, duration, highlights); no text yet, so knowledge search finds no words.' },
};
const fs = factStates[it.fact_state] || factStates.ready;
let html = it.fact_slug ? '<span class="kc-pill" role="status" data-status="' + fs.status + '" data-fact-state="' + escapeHtml(it.fact_state || 'ready') + '" title="' + escapeHtml(fs.title) + '">' + escapeHtml(fs.label) + '</span>' : '';
if (st && st.status) {
const busy = st.status === 'queued' || st.status === 'running';
const pill = st.status === 'done' ? 'ok' : (st.status === 'failed' ? 'error' : (busy ? 'syncing' : ''));
Expand Down Expand Up @@ -47623,7 +47632,10 @@ <h3 class="modal-h">How Agents Use Knowledge (Priming)</h3>
const checked = _inboxSelected.has(key) ? ' checked' : '';
const when = it.recorded_at && !String(it.recorded_at).startsWith('0001') ? relativeTimeShort(it.recorded_at) : '';
const dur = inboxFmtDuration(it.duration_ms);
const meta = [escapeHtml(it.source), when ? 'recorded ' + when : '', dur].filter(Boolean).join(' Β· ');
// The backing Knowledge fact is a plain link in the metadata line, not
// an action: it only opens the fact.
const factLink = it.fact_slug ? '<a href="#" class="inbox-fact-link" data-action="inboxOpenFact" data-prevent="1" data-arg0="' + escapeHtml(it.fact_slug) + '" data-arg1="' + escapeHtml(it.layer || '') + '" title="Open this item\'s Knowledge fact">open in Knowledge</a>' : '';
const meta = [escapeHtml(it.source), when ? 'recorded ' + when : '', dur, factLink].filter(Boolean).join(' Β· ');
const routes = it.routes || {};
let pills = '';
for (const d of Object.keys(routes)) pills += inboxStatePill(d, routes[d]) + ' ';
Expand All @@ -47641,7 +47653,6 @@ <h3 class="modal-h">How Agents Use Knowledge (Priming)</h3>
else actions += '<button type="button" class="hv-btn btn-secondary btn-sm" data-action="inboxUndismiss" data-arg0="' + src + '" data-arg1="' + id + '">Back to inbox</button>';
}
actions += '<button type="button" class="hv-btn btn-secondary btn-sm" data-action="inboxShare" data-arg0="' + src + '" data-arg1="' + id + '" title="Share a link to this item in the Inbox (not the recording)">πŸ”— Share</button>';
if (it.fact_slug) actions += '<button type="button" class="hv-btn btn-secondary btn-sm" data-action="inboxOpenFact" data-arg0="' + escapeHtml(it.fact_slug) + '" data-arg1="' + escapeHtml(it.layer || '') + '" title="This item is already a Knowledge fact">πŸ“š Fact</button>';
return '<div class="kb-fact-item inbox-item" data-inbox-key="' + escapeHtml(key) + '">' +
(owner ? '<label class="inbox-check"><input type="checkbox" data-change-action="inboxToggleSelect" data-arg0="' + src + '" data-arg1="' + id + '"' + checked + ' aria-label="Select ' + escapeHtml(it.title) + '"></label>' : '') +
'<div class="inbox-icon" title="' + src + '">' + inboxSourceIcon(it.source) + '</div>' +
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/inbox/factsource.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import (
"strings"
"time"
"unicode/utf8"

"github.com/hivecommons/hive/pkg/knowledge/connector"
)

// excerptRunes bounds the list excerpt.
Expand Down Expand Up @@ -93,6 +95,7 @@ func itemFromFact(fm map[string]string, body, layer, path string) Item {
it.Summary = truncateRunes(sections["summary"], SummaryRunes)
it.HasTranscript = sections["transcript"] != ""
it.Pending = it.Summary == "" && !it.HasTranscript
it.FactState = factState(fm, it.Pending)
for _, key := range []string{"attr_recorded_at", "synthesized"} {
if t, err := time.Parse(time.RFC3339, fm[key]); err == nil {
it.RecordedAt = t.UTC()
Expand Down Expand Up @@ -131,6 +134,7 @@ func (f *FactSource) Fetch(_ context.Context, it Item) (Content, error) {
sections := splitSections(body)
c.Summary, c.Transcript, c.Highlights = sections["summary"], sections["transcript"], sections["highlights"]
c.Pending = c.Summary == "" && c.Transcript == ""
c.machineFact = connector.FactContentState(fm) == connector.FactContentMachine
return c, nil
}

Expand Down
Loading
Loading