Add opt-in PromptSyntax deployment study analytics

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.1.59"
+version = "0.1.60"
 edition = "2024"
 publish = false
 

apps/gui/frontend/src/api/client.ts

@@ -20,6 +20,8 @@ import type {
   QuotaReport,
   RateLimit,
   RunningTask,
+  StudySummary,
+  StudyTurnMetadata,
   TableSize,
   TaskLogEntry,
   TaskManagerState,
@@ -58,6 +60,7 @@ export interface AgencyZeroApi {
     permission?: Permission;
     /** Reasoning effort, as `Request::effort`. Absent means the CLI's default. */
     effort?: string;
+    study?: StudyTurnMetadata;
   }): Promise<CreatedProject>;
   deleteProject(id: string): Promise<void>;
   /** Stage 3 of the naming design: a manual rename outranks both derived stages. */
@@ -103,13 +106,18 @@ export interface AgencyZeroApi {
     permission?: Permission;
     /** Reasoning effort, as `Request::effort`. Absent means the CLI's default. */
     effort?: string;
+    study?: StudyTurnMetadata;
   }): Promise<Message>;
   /** Approve once / Deny on a moderator hold. */
   resolveModeration(messageId: string, approve: boolean): Promise<Message>;
 
   // — Settings ————————————————————————————————————————————————
   getSettings(): Promise<GlobalSettings>;
   setSettings(patch: DeepPartial<GlobalSettings>): Promise<GlobalSettings>;
+  getStudySummary(): Promise<StudySummary>;
+  /** Native save picker; `null` means it was cancelled. */
+  exportStudyEvents(): Promise<string | null>;
+  clearStudyEvents(): Promise<void>;
   /** Experimental profile only. Fetches usage through Claude Code's managed login. */
   claudeUsage(): Promise<ClaudeUsage>;
   /** Probes the installed CLIs. `recheck` forces a fresh probe. */

apps/gui/frontend/src/api/fixtures.ts

@@ -586,6 +586,7 @@ export const SETTINGS: GlobalSettings = {
   forwardProxyVars: false,
   completedItems: "resolve",
   theme: { accent: "", softness: 0, wash: 10, textBrightness: 0 },
+  studyAnalytics: { enabled: false, sessionId: "", enabledAt: "" },
   notifications: {
     onHold: true,
     onRunFinished: true,

apps/gui/frontend/src/api/index.ts

@@ -41,6 +41,9 @@ const COMMAND_FOR: Partial<Record<keyof AgencyZeroApi, string>> = {
   resolveModeration: "resolve_moderation",
   getSettings: "get_settings",
   setSettings: "set_settings",
+  getStudySummary: "get_study_summary",
+  exportStudyEvents: "export_study_events",
+  clearStudyEvents: "clear_study_events",
   claudeUsage: "claude_usage",
   listAgentStatus: "list_agent_status",
   listModels: "list_models",

apps/gui/frontend/src/api/mock.test.ts

@@ -199,6 +199,25 @@ describe("settings", () => {
     const after = await api.listAgentStatus(true);
     expect(Date.parse(after[0].checkedAt)).toBeGreaterThanOrEqual(Date.parse(before[0].checkedAt));
   });
+
+  it("keeps study collection off until an explicit transition", async () => {
+    const before = await api.getStudySummary();
+    expect(before).toMatchObject({ enabled: false, eventCount: 0, studyId: null });
+
+    const settings = await api.setSettings({ studyAnalytics: { enabled: true } });
+    const started = await api.getStudySummary();
+
+    expect(settings.studyAnalytics.sessionId).toMatch(/^study-/);
+    expect(started).toMatchObject({ enabled: true, eventCount: 1 });
+  });
+
+  it("deletes study rows without silently changing consent", async () => {
+    await api.setSettings({ studyAnalytics: { enabled: true } });
+    await api.setSettings({ studyAnalytics: { enabled: false } });
+    await api.clearStudyEvents();
+
+    expect(await api.getStudySummary()).toMatchObject({ enabled: false, eventCount: 0 });
+  });
 });
 
 describe("rate limits", () => {

apps/gui/frontend/src/api/mock.ts

@@ -11,6 +11,7 @@ import type {
   ProjectStatus,
   QuotaReport,
   RunningTask,
+  StudySummary,
   TaskLogEntry,
 } from "~/types";
 import {
@@ -83,6 +84,7 @@ export function createMockApi(): AgencyZeroApi {
   const agentStatus = clone(fixtures.AGENT_STATUS);
   const models = clone(fixtures.MODEL_CATALOGUE);
   let settings = clone(fixtures.SETTINGS);
+  let studyEventCount = 0;
   const pullRequests = clone(fixtures.PULL_REQUESTS);
   /*
    * What a project's agent kept across a compaction, per project.
@@ -394,10 +396,39 @@ export function createMockApi(): AgencyZeroApi {
     getSettings: () => settle(settings),
 
     async setSettings(patch): Promise<GlobalSettings> {
+      const wasEnabled = settings.studyAnalytics.enabled;
       settings = deepMerge(settings, patch);
+      if (!wasEnabled && settings.studyAnalytics.enabled) {
+        settings.studyAnalytics.sessionId = nextId("study");
+        settings.studyAnalytics.enabledAt = new Date().toISOString();
+        studyEventCount += 1;
+      } else if (wasEnabled && !settings.studyAnalytics.enabled) {
+        studyEventCount += 1;
+      }
       return settle(settings);
     },
 
+    getStudySummary: () =>
+      settle({
+        enabled: settings.studyAnalytics.enabled,
+        studyId: settings.studyAnalytics.sessionId || null,
+        enabledAt: settings.studyAnalytics.enabledAt || null,
+        eventCount: studyEventCount,
+        firstAt: settings.studyAnalytics.enabledAt || null,
+        lastAt: settings.studyAnalytics.enabledAt || null,
+      } satisfies StudySummary),
+
+    // The fixture has no filesystem or durable study table. Cancelling is the
+    // honest save result rather than inventing a file that does not exist.
+    exportStudyEvents: () => settle(null),
+    clearStudyEvents: () => {
+      if (settings.studyAnalytics.enabled) {
+        return Promise.reject(new Error("stop study collection before deleting its stored events"));
+      }
+      studyEventCount = 0;
+      return settle(undefined);
+    },
+
     claudeUsage: () =>
       settle({
         fiveHour: {

apps/gui/frontend/src/api/tauri.ts

@@ -70,6 +70,9 @@ export function createTauriApi(): AgencyZeroApi {
 
     getSettings: () => call("get_settings"),
     setSettings: (patch) => call("set_settings", { patch }),
+    getStudySummary: () => call("get_study_summary"),
+    exportStudyEvents: () => call("export_study_events"),
+    clearStudyEvents: () => call("clear_study_events"),
     claudeUsage: () => call("claude_usage"),
     listAgentStatus: (recheck) => call("list_agent_status", { recheck }),
     listModels: (discover) => call("list_models", { discover }),

apps/gui/frontend/src/features/draft/DraftTab.tsx

@@ -50,7 +50,7 @@ export function DraftTab(props: { tab: Tab }): JSX.Element {
               effort,
             )
           }
-          onSend={(body) => actions.createProject(body, props.tab.key)}
+          onSend={(body, study) => actions.createProject(body, props.tab.key, study)}
         />
       </div>
     </Panel>

apps/gui/frontend/src/features/home/HomeTab.tsx

@@ -9,6 +9,7 @@ import { AgentIoList } from "~/features/project/ProjectPanel";
 import { relativeTime } from "~/lib/format";
 import { AGENT_LABELS, nextStatus, statusSuffix } from "~/lib/labels";
 import { describeError, log } from "~/lib/log";
+import { compileAdvancedPrompt } from "~/lib/promptEditor";
 import { prefs, setPrefs, togglePanelSection } from "~/stores/prefs";
 import { TASK_MANAGER_ID, useWorkspace } from "~/stores/workspace";
 import type { Project, ProjectItem } from "~/types";
@@ -265,17 +266,25 @@ function TaskManagerComposer(): JSX.Element {
   const waitsForRun = () => isRunning() && !canFollowUp();
 
   const submit = async (): Promise<void> => {
+    const authored = draft();
     // The pills become prose on the way out; a file alone is a sendable
     // prompt ("eat this").
-    const body = [draft().trim(), attachments().join("\n")]
+    const body = [authored.trim(), attachments().join("\n")]
       .filter((part) => part.length > 0)
       .join("\n\n");
     if (!body || isSending() || waitsForRun()) return;
 
     setError(null);
     setIsSending(true);
     try {
-      await actions.sendTaskPrompt(body);
+      const parsedAuthored = compileAdvancedPrompt(authored, []);
+      await actions.sendTaskPrompt(body, {
+        authoredCharacterCount: [...authored].length,
+        authoredLineCount:
+          authored.length === 0 ? 0 : authored.replaceAll("\r\n", "\n").split("\n").length,
+        attachmentCount: attachments().length,
+        userAuthoredPs: parsedAuthored.segments.some((segment) => segment.type === "directive"),
+      });
       setDraft("");
       setAttachments([]);
     } catch (cause) {

apps/gui/frontend/src/features/project/Composer.test.tsx

@@ -76,10 +76,33 @@ describe("Composer", () => {
 
     field.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
 
-    await waitFor(() => expect(onSend).toHaveBeenCalledWith("Review the upgrade"));
+    await waitFor(() =>
+      expect(onSend).toHaveBeenCalledWith("Review the upgrade", {
+        authoredCharacterCount: 18,
+        authoredLineCount: 1,
+        attachmentCount: 0,
+        userAuthoredPs: false,
+      }),
+    );
     await waitFor(() => expect(field.value).toBe(""));
   });
 
+  it("detects authored PromptSyntax even when Advanced leaves the message unchanged", async () => {
+    const { field, onSend } = mount();
+    type(field, "@model:sonnet Review this");
+
+    field.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+
+    await waitFor(() =>
+      expect(onSend).toHaveBeenCalledWith("@model:sonnet Review this", {
+        authoredCharacterCount: 25,
+        authoredLineCount: 1,
+        attachmentCount: 0,
+        userAuthoredPs: true,
+      }),
+    );
+  });
+
   /*
    * A prompt is often long and carefully written. Clearing on dispatch and
    * discovering the failure afterwards means it is already gone.
@@ -353,7 +376,14 @@ describe("the alert slot means failure", () => {
     expect(send.disabled).toBe(false);
 
     fireEvent.click(send);
-    await waitFor(() => expect(onSend).toHaveBeenCalledWith("and this should wait its turn"));
+    await waitFor(() =>
+      expect(onSend).toHaveBeenCalledWith("and this should wait its turn", {
+        authoredCharacterCount: 29,
+        authoredLineCount: 1,
+        attachmentCount: 0,
+        userAuthoredPs: false,
+      }),
+    );
   });
 
   it("says nothing when a compaction succeeds", async () => {

apps/gui/frontend/src/features/project/Composer.tsx

@@ -7,7 +7,7 @@ import { compileAdvancedPrompt, type PromptModelOption } from "~/lib/promptEdito
 import { parseSlash } from "~/lib/slash";
 import { prefs, setPrefs } from "~/stores/prefs";
 import { useWorkspace } from "~/stores/workspace";
-import type { Agent, Permission } from "~/types";
+import type { Agent, Permission, StudyTurnMetadata } from "~/types";
 
 const PERMISSION_HINTS: Record<Permission, string> = {
   read_only: "Reads only. The crate default.",
@@ -75,7 +75,7 @@ export type ComposerProps = {
    * Resolves on success. The draft is held until then, so an IPC, database or
    * backend failure cannot swallow a prompt someone spent minutes writing.
    */
-  onSend: (body: string) => Promise<void>;
+  onSend: (body: string, study: StudyTurnMetadata) => Promise<void>;
   /** Shown on the right of the control row, e.g. "31.4k / 200k ctx · 16%". */
   usage?: string;
   /** A run is in flight: the send button becomes Stop. */
@@ -359,7 +359,15 @@ export function Composer(props: ComposerProps): JSX.Element {
         setErrorFor(key, "The prompt contains controls but no message to send.");
         return;
       }
-      await props.onSend(body);
+      const authored = draft();
+      const parsedAuthored = advancedPrompt ?? compileAdvancedPrompt(authored, props.modelOptions);
+      await props.onSend(body, {
+        authoredCharacterCount: [...authored].length,
+        authoredLineCount:
+          authored.length === 0 ? 0 : authored.replaceAll("\r\n", "\n").split("\n").length,
+        attachmentCount: attachments().length,
+        userAuthoredPs: parsedAuthored.segments.some((segment) => segment.type === "directive"),
+      });
       remember("");
       setAttachments([]);
       resize();

apps/gui/frontend/src/features/project/ProjectTab.tsx

@@ -309,7 +309,7 @@ export function ProjectTab(props: { tab: Tab; project: Project }): JSX.Element {
             onPermissionChange={(permission) =>
               actions.setTabModel(props.tab.key, props.tab.agent, props.tab.model, permission)
             }
-            onSend={(body) => actions.send(props.project.id, body)}
+            onSend={(body, study) => actions.send(props.project.id, body, study)}
           />
         </div>
       </Panel>