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
5 changes: 5 additions & 0 deletions .changeset/desktop-persisted-run-queries.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fluentui-react-native/desktop-test': patch
---

Add authorized bounded persisted run/status/artifact queries with opaque IDs, expiring read grants, explicit omissions, and fail-closed terminal evidence. Persist active collector snapshots without starting or replaying workloads when readers reconnect.
5 changes: 4 additions & 1 deletion packages/agentic/desktop-test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@

`@fluentui-react-native/desktop-test` provides application-neutral configuration,
native service composition, process lifetimes, standalone WDIO/Jasmine suites,
and reporting for macOS, Windows, and Win32. It uses
and reporting for macOS, Windows, and Win32. Authorized, bounded persisted
run/status/artifact reads are available from the direct
`./reporting/run-queries` entry; see [reporting](references/reporting.md).
It uses
`@fluentui-react-native/desktop-driver`; Storybook support is an optional
integration in `@fluentui-react-native/storybook-desktop`.

Expand Down
5 changes: 5 additions & 0 deletions packages/agentic/desktop-test/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,11 @@
"import": "./lib/reporting/index.js",
"default": "./src/reporting/index.ts"
},
"./reporting/run-queries": {
"types": "./lib/reporting/runQueries.d.ts",
"import": "./lib/reporting/runQueries.js",
"default": "./src/reporting/runQueries.ts"
},
"./commands": {
"types": "./lib/commands.d.ts",
"import": "./lib/commands.js",
Expand Down
3 changes: 2 additions & 1 deletion packages/agentic/desktop-test/references/current-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ and its sub-issues.
| MCP/WDIO handoff | Work in progress | Must await drain/deletion; attached-app handoff is independent of future supervisor-owned launch. |
| Supervisor-owned app lifetime | Work in progress | Current session-owned launch/externally owned attach semantics remain; never silently retain or terminate another owner's app. |
| Cross-service/multi-target claims | Work in progress | Target aliases and input mutexes are not exact-application exclusion; resolve registered-ID collisions before expanding hosts. |
| Bounded persisted run-query/control API | Work in progress | Schemas belong here. Agents may eventually select only declared workload IDs, not commands/paths/environment. |
| Bounded persisted run/status/artifact queries | Done | Harness-local read service/client; atomic snapshots, terminal evidence, scoped expiring grants, bounded pages and allowlisted opaque artifact IDs. No management transport. |
| Workload management/control API | Work in progress | Future management selects only declared workload IDs, not commands/paths/environment; lifecycle/handoff gates still apply. |
| Automatic service reuse and per-user daemon | Deferred | Requires exact identity/config matching and evidence of need. Never adopt an unknown port occupant. |

See [lifecycle](lifecycle.md), [commands](commands.md), and
Expand Down
82 changes: 82 additions & 0 deletions packages/agentic/desktop-test/references/reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,3 +64,85 @@ directory or render a duplicate summary.

Story-specific readiness, authenticated channel events, and callback execution
are owned by `@fluentui-react-native/storybook-desktop`.

## Persisted read queries

The direct `@fluentui-react-native/desktop-test/reporting/run-queries` entry
exports `DesktopRunQueryService`, `DesktopRunQueryClient`, and their request and
response contracts. This is a harness-local read API, not a management listener,
MCP tool, or execution/recovery API. Its credentials are distinct from driver
control grants. Connecting a reader only binds a credential; it never creates
a workload, producer, controller session, or application.

The collector atomically replaces `run.json` with an active snapshot after each
batch of events (coalesced within a JavaScript turn). Active snapshots have
`terminal: false` and cannot have a passing status. Only successful final
report persistence after producer/output accounting sets `terminal: true`.
Terminal means collection finished, not that coverage passed. A crashed
collector leaves its last snapshot nonterminal. Legacy reports lacking the
marker remain incomplete in queries, even if they say `passed`. Existing
`finishedAt` is the snapshot observation time until the terminal marker is set.
Persisted tests, work, failures, retries, and skips remain the authoritative
source; page size and worker exit codes do not decide coverage.

Trusted host code registers exact collector `{ runId, root, expiresAt }`
records and an optional `textArtifacts` relative-path allowlist, then issues a
read grant with exact `runIds`, an expiry, and optional `artifacts` permission:

```ts
import { DesktopRunQueryService } from '@fluentui-react-native/desktop-test/reporting/run-queries';

const queries = new DesktopRunQueryService(registeredSecrets);
queries.registerRun({
runId: reporter.runId,
root: reporter.root,
expiresAt: retentionDeadline,
textArtifacts: ['commands/build.log'],
});
const credential = queries.issueGrant({
runIds: [reporter.runId],
expiresAt: readerDeadline,
artifacts: true,
});
const client = queries.connect(credential);
const status = await client.query({ operation: 'status', runId: reporter.runId });
```

Registration and grant issuance are **trusted operator/host operations**, never
model-facing inputs. Credentials stay in the host/client binding; requests and
persisted results contain no credentials. Host restart requires explicit
re-registration of retained runs and fresh grants, never execution replay.
The host must register all relevant secrets (including credentials for any
external integration); `addSecret` can update the read redactor. The collector
redacts before persistence, and queries redact again before clipping text.

Readers submit only an opaque run ID, a declared operation, and its bounded
parameters. `status` returns complete counts and terminal/coverage state.
`tests`, `work`, `failures`, and `artifacts` return pages with a default limit of
10 and maximum of 25, capped at 16 KiB. Page IDs do not expose producer IDs or
paths. Text fields are capped at 1 KiB after redaction. `omissions.items` counts
all items absent from that page (including preceding pages);
`omissions.textBytes` counts redacted UTF-8 bytes clipped within returned items.
Opaque `nextCursor` values are bound to the grant, run, collection, and exact
snapshot; a changed snapshot requires a new first page. The last 256 cursors
per grant are retained; older, forged, or cross-grant cursors fail explicitly.

Artifact listing and content both require artifact permission. Listing exposes
only allowlisted artifacts recorded by the collector, with opaque artifact
IDs and descriptions, never paths. `artifact` accepts that ID, not a path,
URL, filename, or command. Content reads return at most 4 KiB of UTF-8 text
with explicit omitted byte counts; binary/invalid UTF-8 is rejected. Raw
`run.json` must be queried structurally, not allowlisted as a text artifact.
Allowlist entries use canonical forward-slash relative paths on every OS;
aliases such as `./run.json` cannot bypass the structural-only rule.
Inputs over 64 MiB for canonical results or 1 MiB for a text artifact fail
explicitly rather than parsing a truncated result as passing. Symlinks, hardlinks,
replaced roots, missing files, malformed results, unauthorized scope, and
expired credentials or retention all fail closed.

`revokeGrant` affects already connected clients. `forgetRun` immediately removes
query authority, including old grants if the host later re-registers that ID.
Retention expiry is checked on every read before any
projection, even if the files remain on disk. This API never deletes collector
files; the host/operator owns filesystem retention cleanup. No reader can
extend retention, enumerate roots, create a grant, or restart a run.
31 changes: 30 additions & 1 deletion packages/agentic/desktop-test/src/reporting/collector.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ export class DesktopRunReporter {
private emittedProblemEvents = 0;
private structuredOutputError?: Error;
private terminal?: DesktopRunResult;
private snapshotQueued = false;

constructor(options: DesktopRunReporterOptions) {
this.options = options;
Expand Down Expand Up @@ -127,6 +128,7 @@ export class DesktopRunReporter {
this.artifacts.set('events.jsonl', 'Versioned event journal');
this.artifacts.set('run.json', 'Canonical run result');
if (options.junit !== false) this.artifacts.set('junit.xml', 'JUnit result');
this.persistSnapshot(this.result());
if (this.reporterMode === 'ndjson') {
const start = {
schemaVersion: 1,
Expand Down Expand Up @@ -255,6 +257,20 @@ export class DesktopRunReporter {
}
this.reduce(event);
this.present(event);
if (!this.snapshotQueued) {
this.snapshotQueued = true;
queueMicrotask(() => {
this.snapshotQueued = false;
if (this.finished) return;
try {
this.persistSnapshot(this.result());
} catch (error) {
const failure = this.failure(error, 'reporting');
this.failures.set(failure.failureId, failure);
this.logger.error(`Cannot persist desktop run snapshot: ${failure.error.message}`);
}
});
}
}

private reduce(event: CollectedDesktopEvent): void {
Expand Down Expand Up @@ -497,7 +513,18 @@ export class DesktopRunReporter {
fs.renameSync(temporary, this.artifactPath(name));
};
if (this.options.junit !== false) write('junit.xml', renderJUnit(result));
write('run.json', JSON.stringify(result, null, 2) + '\n');
this.persistSnapshot(result);
}

private persistSnapshot(result: DesktopRunResult): void {
const temporary = this.artifactPath('run.json.tmp');
const snapshot = this.sanitize({
...result,
terminal: result.terminal === true,
status: result.terminal === true || result.status === 'failed' ? result.status : 'incomplete',
});
fs.writeFileSync(temporary, JSON.stringify(snapshot) + '\n', { mode: 0o600 });
fs.renameSync(temporary, this.artifactPath('run.json'));
}

private async finalize(): Promise<DesktopRunResult> {
Expand Down Expand Up @@ -603,6 +630,8 @@ export class DesktopRunReporter {
// A closed stderr cannot carry the reporting diagnostic.
}
}
result = { ...this.result(), terminal: true };
this.persist(result);
this.finished = true;
this.terminal = result;
return result;
Expand Down
2 changes: 2 additions & 0 deletions packages/agentic/desktop-test/src/reporting/results.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ export type DesktopRunResult = {
runId: string;
kind: 'tests' | 'lifecycle';
status: TestStatus;
/** Only true after collector finalization; absent in legacy reports. */
terminal?: boolean;
startedAt: string;
finishedAt: string;
durationMs: number;
Expand Down
Loading
Loading