@codingame/monaco-vscode-workbench-service-override 37.6.0 → 38.0.0

package/vscode/src/vs/sessions/contrib/sessions/browser/sessionsLifecycleTracker.d.ts

@@ -0,0 +1,192 @@
+import { Disposable } from "@codingame/monaco-vscode-api/vscode/vs/base/common/lifecycle";
+import { URI } from "@codingame/monaco-vscode-api/vscode/vs/base/common/uri";
+import { IStorageService } from "@codingame/monaco-vscode-api/vscode/vs/platform/storage/common/storage.service";
+import { AGENTS_WINDOW_TOTAL_SESSIONS_STORAGE_KEY as TOTAL_SESSIONS_KEY } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/constants";
+import { ISession } from "@codingame/monaco-vscode-api/vscode/vs/sessions/services/sessions/common/session";
+import { PullRequestStatus } from "@codingame/monaco-vscode-api/vscode/vs/sessions/contrib/github/common/types";
+/** Storage key for the per-session lifecycle stats map (JSON encoded). Exported for tests. */
+export declare const SESSIONS_KEY = "agentSessions.telemetry.summary.sessions";
+export { TOTAL_SESSIONS_KEY };
+/** Hard cap on the number of tracked sessions to prevent unbounded storage growth. Exported for tests. */
+export declare const MAX_TRACKED_SESSIONS = 2000;
+/**
+ * Hard cap on the number of distinct typed-in files remembered per session.
+ * Beyond this the reported count saturates, which keeps persisted state
+ * bounded for sessions that touch very many files. Exported for tests.
+ */
+export declare const MAX_TYPED_FILES_PER_SESSION = 250;
+/** Reason a session is considered "done" and the summary is emitted. */
+export type SessionDoneReason = "archived" | "deleted" | "archivedRemotely" | "deletedRemotely";
+/**
+ * Cumulative user-request counters maintained by {@link SessionsLifecycleTracker}.
+ * The values are returned post-increment by
+ * {@link SessionsLifecycleTracker.incrementAndGetUserRequestCounters}, or read
+ * unchanged via {@link SessionsLifecycleTracker.getUserRequestCounters}.
+ */
+export interface IUserRequestCounters {
+    readonly userSessionsTotal: number;
+    readonly userSessionsInWorkspace: number;
+    readonly userSessionsForProvider: number;
+}
+/** Keys of {@link IStoredSessionStats} that hold simple incrementable counters. */
+export type SessionLifecycleCounterKey = "feedbackAdded" | "feedbackConverted" | "feedbackReplyAdded" | "feedbackSubmitted" | "createPullRequest" | "createDraftPullRequest" | "updatePullRequest" | "mergePullRequest" | "checkoutPullRequest" | "initializeRepository" | "commit" | "commitAndSync" | "sessionRestored" | "stickinessToggled" | "maximizeToggled" | "chatDeleted" | "chatRenamed" | "sessionRenamed" | "fixCIChecks" | "taskRun";
+/**
+ * Flat summary produced by {@link SessionsLifecycleTracker.finalize}. The
+ * shape matches the fields of the `agents/sessionSummary` telemetry event
+ * declared in `sessionsTelemetry.contribution.ts`.
+ */
+export interface ISessionLifecycleSummary {
+    agentSessionId: string;
+    providerId: string;
+    providerType: string;
+    isolationKind: "worktree" | "folder";
+    workspaceHash: string;
+    hasGitRepository: boolean;
+    isVirtualWorkspace: boolean;
+    isExternal: boolean;
+    isMultiRoot: boolean;
+    folderCount: number;
+    gitFolderCount: number;
+    nonGitFolderCount: number;
+    doneReason: SessionDoneReason;
+    firstRequestSentInThisClient: boolean;
+    hasWorktreeCreatedTask: boolean | undefined;
+    configuredTasksCount: number | undefined;
+    timeSinceFirstObservedMs: number;
+    timeSinceFirstRequestMs: number;
+    appLaunchesSinceFirstObserved: number;
+    requestsSent: number;
+    chatCount: number;
+    feedbackAdded: number;
+    feedbackConverted: number;
+    feedbackReplyAdded: number;
+    feedbackSubmitted: number;
+    createPullRequest: number;
+    createDraftPullRequest: number;
+    updatePullRequest: number;
+    mergePullRequest: number;
+    checkoutPullRequest: number;
+    initializeRepository: number;
+    commit: number;
+    commitAndSync: number;
+    sessionRestored: number;
+    stickinessToggled: number;
+    maximizeToggled: number;
+    chatDeleted: number;
+    chatRenamed: number;
+    sessionRenamed: number;
+    fixCIChecks: number;
+    taskRun: number;
+    typedCharacters: number;
+    typedFileCount: number;
+    filesChanged: number;
+    linesAdded: number;
+    linesDeleted: number;
+    pullRequestCount: number;
+    pullRequestStatus: PullRequestStatus | undefined;
+    pullRequestArtifactMergedCount: number;
+    pullRequestArtifactOpenCount: number;
+    pullRequestArtifactDraftCount: number;
+    pullRequestArtifactClosedCount: number;
+    issueArtifactCount: number;
+    otherArtifactCount: number;
+    artifactCount: number;
+    referenceCount: number;
+    userSessionsTotal: number;
+    userSessionsInWorkspace: number;
+    userSessionsForProvider: number;
+}
+/**
+ * Tracks per-session lifecycle stats for the `agents/sessionSummary` telemetry
+ * event. Tracking starts the first time the user interacts with a session in
+ * this client (sending a request, running a session-scoped command, adding
+ * feedback, …) and ends when the session is considered done — locally
+ * archived/deleted or observed as archived/deleted via the provider (i.e.,
+ * the user finished it in a different client).
+ *
+ * State is persisted in application-scoped storage so a session opened today
+ * and archived next week — possibly across many app launches and in a
+ * different workspace — still produces a single summary event covering the
+ * entire lifetime.
+ */
+export declare class SessionsLifecycleTracker extends Disposable {
+    private readonly _storageService;
+    private readonly _appLaunchCount;
+    private readonly _stats;
+    private readonly _usage;
+    constructor(_storageService: IStorageService, appLaunchCount: number);
+    /** Record a request that creates a new chat for the given session. Bumps both `requestsSent` and `chatCount`. */
+    recordNewChatRequestSent(session: ISession): void;
+    /** Record a follow-up request within an existing chat. Bumps `requestsSent` but not `chatCount`. */
+    recordRequestSent(session: ISession): void;
+    private _recordRequestSent;
+    /**
+     * Records task-related state observed at the time of the first user
+     * request for the given session. Only the first call per tracked session
+     * has an effect; subsequent calls are ignored.
+     */
+    recordFirstRequestTaskInfo(session: ISession, info: {
+        readonly hasWorktreeCreatedTask: boolean;
+        readonly configuredTasksCount: number;
+    }): void;
+    /** Increment a named counter. Creates a tracking entry if the session is not yet tracked. */
+    bumpCounter(session: ISession, key: SessionLifecycleCounterKey): void;
+    /**
+     * Adds characters the user manually typed into `resource`, which must live
+     * in the session's workspace folders. Unlike {@link bumpCounter} this never
+     * starts tracking a session: editing a folder is not by itself an
+     * interaction with the session that happens to use it.
+     *
+     * `resource` is only used to tell files apart for {@link ISessionLifecycleSummary.typedFileCount}
+     * and is stored as a hash, never as a path.
+     */
+    addTypedCharacters(sessionId: string, resource: URI, characters: number): void;
+    /** Refresh observed session state (pull requests, changes) for a tracked session. No-op when not tracked. */
+    updateSessionState(session: ISession): void;
+    /**
+     * Increments the persisted user-request counters (total, per-workspace,
+     * per-provider) and returns the new values. Should be called once per
+     * brand-new session the user starts from the Agents window.
+     */
+    incrementAndGetUserRequestCounters(session: ISession): IUserRequestCounters;
+    /** Reads the persisted user-request counters without incrementing them. */
+    getUserRequestCounters(session: ISession): IUserRequestCounters;
+    /** Whether the given session id has a tracking entry. */
+    isTracked(sessionId: string): boolean;
+    /** Snapshot of tracked session ids. */
+    getTrackedIds(): string[];
+    /** Snapshot of tracked sessions as `(sessionId, providerId)` pairs. */
+    getTrackedEntries(): readonly {
+        readonly sessionId: string;
+        readonly providerId: string;
+    }[];
+    /**
+     * Build a summary for the given tracked session and remove its entry.
+     * Returns `undefined` if the session was not tracked (e.g., already
+     * finalized by a competing event).
+     */
+    finalize(sessionId: string, reason: SessionDoneReason, finalSession?: ISession): ISessionLifecycleSummary | undefined;
+    private _readUserRequestCountersForSummary;
+    private _readUserRequestCounters;
+    private _readProviderCounterMap;
+    private _readCounterMap;
+    private _ensure;
+    /**
+     * Refreshes the parts of the entry that mirror live session state, so the
+     * summary reports what was last observed rather than what was known when
+     * tracking started.
+     */
+    private _updateObservedState;
+    /**
+     * Refreshes the folder counts. A session's workspace is resolved
+     * asynchronously and can gain folders later, so the counts known when
+     * tracking started are not what the user ended up working with.
+     */
+    private _updateWorkspaceTopology;
+    private _updatePullRequestState;
+    private _updateArtifactCounts;
+    private _updateChangesSummary;
+    private _evictOldest;
+    private _load;
+    private _save;
+}