agent-inspect 3.5.4 → 4.0.0

package/packages/core/dist/workspace.d.cts

@@ -0,0 +1,220 @@
+/**
+ * Internal workspace manifest types (v4.0).
+ *
+ * @remarks
+ * Experimental and internal to `@agent-inspect/core`. This module is not part
+ * of any published entry point. Adding a public `agent-inspect/workspace`
+ * export is a separate, maintainer-gated step (see
+ * `docs/proposals/LOCAL-TRACE-WORKSPACE.md`).
+ */
+/** Fixed manifest schema version for the v4.0 workspace model. */
+declare const WORKSPACE_SCHEMA_VERSION: "1.0";
+/** Standard workspace directory name at a project root. */
+declare const WORKSPACE_DIR_NAME: ".agent-inspect";
+/** Standard manifest filename inside {@link WORKSPACE_DIR_NAME}. */
+declare const WORKSPACE_MANIFEST_FILENAME: "workspace.json";
+/** Default share-safety posture applied to a workspace. */
+type WorkspaceRedactionProfile = "local" | "share" | "strict";
+/** Optional local index kind (SQLite index arrives as an opt-in package in v4.1). */
+type WorkspaceIndexType = "none" | "sqlite" | "custom";
+/** Optional local index descriptor. */
+interface WorkspaceIndexConfig {
+    enabled: boolean;
+    type: WorkspaceIndexType;
+    path?: string;
+}
+/**
+ * The `.agent-inspect/workspace.json` manifest.
+ *
+ * @remarks
+ * All directory fields are paths relative to the workspace root and must
+ * resolve inside it (no absolute paths, no `..` traversal).
+ */
+interface AgentInspectWorkspaceManifest {
+    schemaVersion: typeof WORKSPACE_SCHEMA_VERSION;
+    project: string;
+    createdAt: string;
+    traceDirs: string[];
+    reportsDir: string;
+    artifactsDir: string;
+    bundlesDir: string;
+    notesDir: string;
+    redactionProfile: WorkspaceRedactionProfile;
+    index: WorkspaceIndexConfig;
+}
+/** Result of validating unknown input against the manifest contract. */
+interface WorkspaceManifestValidationResult {
+    ok: boolean;
+    manifest?: AgentInspectWorkspaceManifest;
+    errors: string[];
+    warnings: string[];
+}
+
+/**
+ * Internal workspace manifest validation + default generation (v4.0).
+ *
+ * @remarks
+ * Pure, non-throwing helpers. Validation is conservative: unknown or malformed
+ * input is rejected with clear messages rather than coerced. No filesystem or
+ * network access happens here (filesystem helpers arrive in a later chunk).
+ */
+/** Default relative layout used when generating a fresh manifest. */
+declare const DEFAULT_WORKSPACE_LAYOUT: {
+    readonly traceDirs: readonly ["runs"];
+    readonly reportsDir: "reports";
+    readonly artifactsDir: "artifacts";
+    readonly bundlesDir: "bundles";
+    readonly notesDir: "notes";
+};
+/** Upper bound on serialized manifest input accepted by {@link parseWorkspaceManifest}. */
+declare const MAX_WORKSPACE_MANIFEST_BYTES: number;
+/** Options for {@link createDefaultWorkspaceManifest}. */
+interface CreateWorkspaceManifestOptions {
+    project: string;
+    createdAt?: string;
+    traceDirs?: string[];
+    reportsDir?: string;
+    artifactsDir?: string;
+    bundlesDir?: string;
+    notesDir?: string;
+    redactionProfile?: WorkspaceRedactionProfile;
+    index?: Partial<WorkspaceIndexConfig>;
+}
+/**
+ * Generates a default workspace manifest for a project using the standard
+ * layout. The returned object is always shape-valid.
+ */
+declare function createDefaultWorkspaceManifest(options: CreateWorkspaceManifestOptions): AgentInspectWorkspaceManifest;
+/**
+ * Returns true when `p` is a non-empty relative path that stays within the
+ * workspace root: no absolute paths, no `..` traversal, no Windows drive roots.
+ */
+declare function isSafeRelativeWorkspacePath(p: unknown): p is string;
+/**
+ * Conservatively validates unknown input against the workspace manifest
+ * contract. Never throws; returns a result with `ok`, the normalized
+ * `manifest` (when valid), `errors`, and non-fatal `warnings`.
+ */
+declare function validateWorkspaceManifest(input: unknown): WorkspaceManifestValidationResult;
+/**
+ * Safely parses a serialized manifest string and validates it. Bounds input
+ * size and rejects invalid JSON without throwing.
+ */
+declare function parseWorkspaceManifest(json: string): WorkspaceManifestValidationResult;
+/** Serializes a manifest to deterministic, pretty-printed JSON with a trailing newline. */
+declare function serializeWorkspaceManifest(manifest: AgentInspectWorkspaceManifest): string;
+
+/**
+ * Internal workspace filesystem helpers (v4.0).
+ *
+ * @remarks
+ * Local-only. Never deletes trace files. All manifest-derived paths are
+ * resolved and confirmed to stay within the workspace directory
+ * (path-traversal guarded). No network access.
+ */
+/** Resolved on-disk location of a workspace. */
+interface WorkspaceLocation {
+    /** Project directory that contains the `.agent-inspect` folder. */
+    projectRoot: string;
+    /** The `.agent-inspect` workspace directory (root for relative manifest paths). */
+    workspaceDir: string;
+    /** Absolute path to `workspace.json`. */
+    manifestPath: string;
+}
+/** Resolves the workspace location for a given project directory. */
+declare function resolveWorkspaceLocation(cwd?: string): WorkspaceLocation;
+/**
+ * Resolves a manifest-relative path against the workspace directory, rejecting
+ * any path that escapes it.
+ */
+declare function resolveInsideWorkspace(workspaceDir: string, relative: string): string;
+/** Result of reading a workspace manifest from disk. */
+interface ReadWorkspaceManifestResult {
+    exists: boolean;
+    ok: boolean;
+    manifest?: AgentInspectWorkspaceManifest;
+    errors: string[];
+    warnings: string[];
+}
+/** Reads and validates `workspace.json` at the given location. Never throws. */
+declare function readWorkspaceManifestFile(location: WorkspaceLocation): Promise<ReadWorkspaceManifestResult>;
+/** Options for {@link createWorkspace}. */
+interface CreateWorkspaceOptions {
+    cwd?: string;
+    project?: string;
+    redactionProfile?: WorkspaceRedactionProfile;
+    /** Preview only: do not write anything to disk. */
+    dryRun?: boolean;
+}
+/** Outcome of {@link createWorkspace}. */
+interface CreateWorkspaceResult {
+    location: WorkspaceLocation;
+    manifest: AgentInspectWorkspaceManifest;
+    /** True when a fresh manifest was written. */
+    created: boolean;
+    /** True when an existing workspace/trace directory was adopted without rewrite. */
+    adopted: boolean;
+    /** Relative directories created (or that would be created in dry-run). */
+    createdDirs: string[];
+    /** True when top-level `.jsonl` traces were detected and preserved. */
+    detectedExistingTraces: boolean;
+    dryRun: boolean;
+}
+/**
+ * Creates or adopts a workspace. Never deletes or rewrites existing traces.
+ * When a manifest already exists it is adopted (missing folders are created,
+ * the manifest is left untouched).
+ */
+declare function createWorkspace(options?: CreateWorkspaceOptions): Promise<CreateWorkspaceResult>;
+/** Index presence/status for {@link getWorkspaceStatus}. */
+interface WorkspaceIndexStatus {
+    enabled: boolean;
+    type: string;
+    exists: boolean;
+}
+/** Aggregate, read-only workspace status. */
+interface WorkspaceStatus {
+    project: string;
+    traceFiles: number;
+    reports: number;
+    artifacts: number;
+    bundles: number;
+    notes: number;
+    index: WorkspaceIndexStatus;
+}
+/** Computes read-only counts for a workspace. Requires a valid manifest. */
+declare function getWorkspaceStatus(location: WorkspaceLocation, manifest: AgentInspectWorkspaceManifest): Promise<WorkspaceStatus>;
+/** A single workspace doctor check. */
+interface WorkspaceDoctorCheck {
+    id: string;
+    status: "pass" | "warn" | "fail";
+    message: string;
+}
+/** Result of {@link doctorWorkspace}. */
+interface WorkspaceDoctorResult {
+    ok: boolean;
+    checks: WorkspaceDoctorCheck[];
+}
+/**
+ * Validates a workspace: manifest presence/shape, folder permissions, trace
+ * readability, and index staleness. Read-only; never throws.
+ */
+declare function doctorWorkspace(location: WorkspaceLocation): Promise<WorkspaceDoctorResult>;
+/** Options for {@link cleanWorkspace}. */
+interface CleanWorkspaceOptions {
+    /** Actually delete. When false (default), the operation is a dry-run. */
+    confirm?: boolean;
+}
+/** Result of {@link cleanWorkspace}. */
+interface CleanWorkspaceResult {
+    dryRun: boolean;
+    /** Relative paths removed (or that would be removed in dry-run). */
+    removed: string[];
+}
+/**
+ * Removes generated workspace content (reports, artifacts, bundles, index).
+ * Dry-run by default; trace directories are never touched.
+ */
+declare function cleanWorkspace(location: WorkspaceLocation, manifest: AgentInspectWorkspaceManifest, options?: CleanWorkspaceOptions): Promise<CleanWorkspaceResult>;
+
+export { type AgentInspectWorkspaceManifest, type CleanWorkspaceOptions, type CleanWorkspaceResult, type CreateWorkspaceManifestOptions, type CreateWorkspaceOptions, type CreateWorkspaceResult, DEFAULT_WORKSPACE_LAYOUT, MAX_WORKSPACE_MANIFEST_BYTES, type ReadWorkspaceManifestResult, WORKSPACE_DIR_NAME, WORKSPACE_MANIFEST_FILENAME, WORKSPACE_SCHEMA_VERSION, type WorkspaceDoctorCheck, type WorkspaceDoctorResult, type WorkspaceIndexConfig, type WorkspaceIndexStatus, type WorkspaceIndexType, type WorkspaceLocation, type WorkspaceManifestValidationResult, type WorkspaceRedactionProfile, type WorkspaceStatus, cleanWorkspace, createDefaultWorkspaceManifest, createWorkspace, doctorWorkspace, getWorkspaceStatus, isSafeRelativeWorkspacePath, parseWorkspaceManifest, readWorkspaceManifestFile, resolveInsideWorkspace, resolveWorkspaceLocation, serializeWorkspaceManifest, validateWorkspaceManifest };

package/packages/core/dist/workspace.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Internal workspace manifest types (v4.0).
+ *
+ * @remarks
+ * Experimental and internal to `@agent-inspect/core`. This module is not part
+ * of any published entry point. Adding a public `agent-inspect/workspace`
+ * export is a separate, maintainer-gated step (see
+ * `docs/proposals/LOCAL-TRACE-WORKSPACE.md`).
+ */
+/** Fixed manifest schema version for the v4.0 workspace model. */
+declare const WORKSPACE_SCHEMA_VERSION: "1.0";
+/** Standard workspace directory name at a project root. */
+declare const WORKSPACE_DIR_NAME: ".agent-inspect";
+/** Standard manifest filename inside {@link WORKSPACE_DIR_NAME}. */
+declare const WORKSPACE_MANIFEST_FILENAME: "workspace.json";
+/** Default share-safety posture applied to a workspace. */
+type WorkspaceRedactionProfile = "local" | "share" | "strict";
+/** Optional local index kind (SQLite index arrives as an opt-in package in v4.1). */
+type WorkspaceIndexType = "none" | "sqlite" | "custom";
+/** Optional local index descriptor. */
+interface WorkspaceIndexConfig {
+    enabled: boolean;
+    type: WorkspaceIndexType;
+    path?: string;
+}
+/**
+ * The `.agent-inspect/workspace.json` manifest.
+ *
+ * @remarks
+ * All directory fields are paths relative to the workspace root and must
+ * resolve inside it (no absolute paths, no `..` traversal).
+ */
+interface AgentInspectWorkspaceManifest {
+    schemaVersion: typeof WORKSPACE_SCHEMA_VERSION;
+    project: string;
+    createdAt: string;
+    traceDirs: string[];
+    reportsDir: string;
+    artifactsDir: string;
+    bundlesDir: string;
+    notesDir: string;
+    redactionProfile: WorkspaceRedactionProfile;
+    index: WorkspaceIndexConfig;
+}
+/** Result of validating unknown input against the manifest contract. */
+interface WorkspaceManifestValidationResult {
+    ok: boolean;
+    manifest?: AgentInspectWorkspaceManifest;
+    errors: string[];
+    warnings: string[];
+}
+
+/**
+ * Internal workspace manifest validation + default generation (v4.0).
+ *
+ * @remarks
+ * Pure, non-throwing helpers. Validation is conservative: unknown or malformed
+ * input is rejected with clear messages rather than coerced. No filesystem or
+ * network access happens here (filesystem helpers arrive in a later chunk).
+ */
+/** Default relative layout used when generating a fresh manifest. */
+declare const DEFAULT_WORKSPACE_LAYOUT: {
+    readonly traceDirs: readonly ["runs"];
+    readonly reportsDir: "reports";
+    readonly artifactsDir: "artifacts";
+    readonly bundlesDir: "bundles";
+    readonly notesDir: "notes";
+};
+/** Upper bound on serialized manifest input accepted by {@link parseWorkspaceManifest}. */
+declare const MAX_WORKSPACE_MANIFEST_BYTES: number;
+/** Options for {@link createDefaultWorkspaceManifest}. */
+interface CreateWorkspaceManifestOptions {
+    project: string;
+    createdAt?: string;
+    traceDirs?: string[];
+    reportsDir?: string;
+    artifactsDir?: string;
+    bundlesDir?: string;
+    notesDir?: string;
+    redactionProfile?: WorkspaceRedactionProfile;
+    index?: Partial<WorkspaceIndexConfig>;
+}
+/**
+ * Generates a default workspace manifest for a project using the standard
+ * layout. The returned object is always shape-valid.
+ */
+declare function createDefaultWorkspaceManifest(options: CreateWorkspaceManifestOptions): AgentInspectWorkspaceManifest;
+/**
+ * Returns true when `p` is a non-empty relative path that stays within the
+ * workspace root: no absolute paths, no `..` traversal, no Windows drive roots.
+ */
+declare function isSafeRelativeWorkspacePath(p: unknown): p is string;
+/**
+ * Conservatively validates unknown input against the workspace manifest
+ * contract. Never throws; returns a result with `ok`, the normalized
+ * `manifest` (when valid), `errors`, and non-fatal `warnings`.
+ */
+declare function validateWorkspaceManifest(input: unknown): WorkspaceManifestValidationResult;
+/**
+ * Safely parses a serialized manifest string and validates it. Bounds input
+ * size and rejects invalid JSON without throwing.
+ */
+declare function parseWorkspaceManifest(json: string): WorkspaceManifestValidationResult;
+/** Serializes a manifest to deterministic, pretty-printed JSON with a trailing newline. */
+declare function serializeWorkspaceManifest(manifest: AgentInspectWorkspaceManifest): string;
+
+/**
+ * Internal workspace filesystem helpers (v4.0).
+ *
+ * @remarks
+ * Local-only. Never deletes trace files. All manifest-derived paths are
+ * resolved and confirmed to stay within the workspace directory
+ * (path-traversal guarded). No network access.
+ */
+/** Resolved on-disk location of a workspace. */
+interface WorkspaceLocation {
+    /** Project directory that contains the `.agent-inspect` folder. */
+    projectRoot: string;
+    /** The `.agent-inspect` workspace directory (root for relative manifest paths). */
+    workspaceDir: string;
+    /** Absolute path to `workspace.json`. */
+    manifestPath: string;
+}
+/** Resolves the workspace location for a given project directory. */
+declare function resolveWorkspaceLocation(cwd?: string): WorkspaceLocation;
+/**
+ * Resolves a manifest-relative path against the workspace directory, rejecting
+ * any path that escapes it.
+ */
+declare function resolveInsideWorkspace(workspaceDir: string, relative: string): string;
+/** Result of reading a workspace manifest from disk. */
+interface ReadWorkspaceManifestResult {
+    exists: boolean;
+    ok: boolean;
+    manifest?: AgentInspectWorkspaceManifest;
+    errors: string[];
+    warnings: string[];
+}
+/** Reads and validates `workspace.json` at the given location. Never throws. */
+declare function readWorkspaceManifestFile(location: WorkspaceLocation): Promise<ReadWorkspaceManifestResult>;
+/** Options for {@link createWorkspace}. */
+interface CreateWorkspaceOptions {
+    cwd?: string;
+    project?: string;
+    redactionProfile?: WorkspaceRedactionProfile;
+    /** Preview only: do not write anything to disk. */
+    dryRun?: boolean;
+}
+/** Outcome of {@link createWorkspace}. */
+interface CreateWorkspaceResult {
+    location: WorkspaceLocation;
+    manifest: AgentInspectWorkspaceManifest;
+    /** True when a fresh manifest was written. */
+    created: boolean;
+    /** True when an existing workspace/trace directory was adopted without rewrite. */
+    adopted: boolean;
+    /** Relative directories created (or that would be created in dry-run). */
+    createdDirs: string[];
+    /** True when top-level `.jsonl` traces were detected and preserved. */
+    detectedExistingTraces: boolean;
+    dryRun: boolean;
+}
+/**
+ * Creates or adopts a workspace. Never deletes or rewrites existing traces.
+ * When a manifest already exists it is adopted (missing folders are created,
+ * the manifest is left untouched).
+ */
+declare function createWorkspace(options?: CreateWorkspaceOptions): Promise<CreateWorkspaceResult>;
+/** Index presence/status for {@link getWorkspaceStatus}. */
+interface WorkspaceIndexStatus {
+    enabled: boolean;
+    type: string;
+    exists: boolean;
+}
+/** Aggregate, read-only workspace status. */
+interface WorkspaceStatus {
+    project: string;
+    traceFiles: number;
+    reports: number;
+    artifacts: number;
+    bundles: number;
+    notes: number;
+    index: WorkspaceIndexStatus;
+}
+/** Computes read-only counts for a workspace. Requires a valid manifest. */
+declare function getWorkspaceStatus(location: WorkspaceLocation, manifest: AgentInspectWorkspaceManifest): Promise<WorkspaceStatus>;
+/** A single workspace doctor check. */
+interface WorkspaceDoctorCheck {
+    id: string;
+    status: "pass" | "warn" | "fail";
+    message: string;
+}
+/** Result of {@link doctorWorkspace}. */
+interface WorkspaceDoctorResult {
+    ok: boolean;
+    checks: WorkspaceDoctorCheck[];
+}
+/**
+ * Validates a workspace: manifest presence/shape, folder permissions, trace
+ * readability, and index staleness. Read-only; never throws.
+ */
+declare function doctorWorkspace(location: WorkspaceLocation): Promise<WorkspaceDoctorResult>;
+/** Options for {@link cleanWorkspace}. */
+interface CleanWorkspaceOptions {
+    /** Actually delete. When false (default), the operation is a dry-run. */
+    confirm?: boolean;
+}
+/** Result of {@link cleanWorkspace}. */
+interface CleanWorkspaceResult {
+    dryRun: boolean;
+    /** Relative paths removed (or that would be removed in dry-run). */
+    removed: string[];
+}
+/**
+ * Removes generated workspace content (reports, artifacts, bundles, index).
+ * Dry-run by default; trace directories are never touched.
+ */
+declare function cleanWorkspace(location: WorkspaceLocation, manifest: AgentInspectWorkspaceManifest, options?: CleanWorkspaceOptions): Promise<CleanWorkspaceResult>;
+
+export { type AgentInspectWorkspaceManifest, type CleanWorkspaceOptions, type CleanWorkspaceResult, type CreateWorkspaceManifestOptions, type CreateWorkspaceOptions, type CreateWorkspaceResult, DEFAULT_WORKSPACE_LAYOUT, MAX_WORKSPACE_MANIFEST_BYTES, type ReadWorkspaceManifestResult, WORKSPACE_DIR_NAME, WORKSPACE_MANIFEST_FILENAME, WORKSPACE_SCHEMA_VERSION, type WorkspaceDoctorCheck, type WorkspaceDoctorResult, type WorkspaceIndexConfig, type WorkspaceIndexStatus, type WorkspaceIndexType, type WorkspaceLocation, type WorkspaceManifestValidationResult, type WorkspaceRedactionProfile, type WorkspaceStatus, cleanWorkspace, createDefaultWorkspaceManifest, createWorkspace, doctorWorkspace, getWorkspaceStatus, isSafeRelativeWorkspacePath, parseWorkspaceManifest, readWorkspaceManifestFile, resolveInsideWorkspace, resolveWorkspaceLocation, serializeWorkspaceManifest, validateWorkspaceManifest };