@praxis-ai/praxis 0.1.0

package/dist/storagePool/baseToolStorage/computeruseBase/microphoneAccess/computeruse.microphonePermissionRequest/bestPractice.js

@@ -0,0 +1,143 @@
+import { buildComputerUsePracticeAuditMetadata, createComputerUseBaseToolDefinition, createComputerUseCoreHandler, injectRuntimeInvocationMetadata, jsonSchema, selectComputerUseProviderPractice, } from "../../_shared/baseToolAdapter.js";
+import { anthropicMicrophonePermissionRequestPractice } from "./anthropic.js";
+import { deepmindMicrophonePermissionRequestPractice } from "./deepmind.js";
+import { microphonePermissionRequestDependencyDeclarations, } from "./dependencies.js";
+import { openaiMicrophonePermissionRequestPractice } from "./openai.js";
+import { executeMicrophonePermissionRequest as executeMicrophonePermissionRequestCore, microphonePermissionRequestDescriptor, planMicrophonePermissionRequest, } from "./core.js";
+export const microphonePermissionRequestProviderPractices = [
+    anthropicMicrophonePermissionRequestPractice,
+    openaiMicrophonePermissionRequestPractice,
+    deepmindMicrophonePermissionRequestPractice,
+];
+export const microphonePermissionRequestBestPracticeDescriptor = {
+    toolId: "computeruse.microphonePermissionRequest",
+    bestPractice: "storage-owned-runtime-computeruse-microphone-permission-provider-practice-evidence",
+    sourcePriority: ["cli", "agent-sdk", "api-sdk", "praxis-native"],
+    providerOrder: ["anthropic", "openai", "deepmind"],
+    dependencies: microphonePermissionRequestDependencyDeclarations,
+};
+const praxisNativeFallbackPractice = {
+    providerName: "praxis-native",
+    source: {
+        kind: "praxis-native",
+        label: "Praxis dry-run fallback",
+    },
+    directCliSupport: false,
+    sideEffectPolicy: "runtime-governed",
+    notes: ["No runtime computeruse microphone permission provider is available; dry-run remains available."],
+    createProvider: () => undefined,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeContextWithAuditMetadata(context, auditMetadata) {
+    if (!isRecord(context)) {
+        return { auditMetadata };
+    }
+    return {
+        ...context,
+        auditMetadata: {
+            ...(isRecord(context.auditMetadata) ? context.auditMetadata : {}),
+            ...auditMetadata,
+        },
+    };
+}
+export function selectMicrophonePermissionRequestPractice(dependencies = {}) {
+    return selectComputerUseProviderPractice(microphonePermissionRequestProviderPractices, dependencies, praxisNativeFallbackPractice);
+}
+export async function executeMicrophonePermissionRequest(request = {}) {
+    const selection = selectMicrophonePermissionRequestPractice({
+        executor: request.executor,
+        provider: request.provider,
+        preferredProvider: request.preferredProvider,
+    });
+    const auditMetadata = buildComputerUsePracticeAuditMetadata(selection);
+    return executeMicrophonePermissionRequestCore({
+        ...request,
+        provider: selection.provider,
+        context: mergeContextWithAuditMetadata(request.context, auditMetadata),
+    });
+}
+export const microphonePermissionRequestBaseToolDefinition = createComputerUseBaseToolDefinition({
+    toolId: microphonePermissionRequestDescriptor.toolId,
+    title: "Computer Use Microphone Permission Request",
+    description: "Request microphone access through governed runtime computer-use support.",
+    summary: "Use computeruse.microphonePermissionRequest to ask runtime for a microphone permission lease.",
+    storageGroup: "microphoneAccess",
+    riskLevel: "risky",
+    permissionHints: ["device:microphone", "microphone:permission-request"],
+    dependencies: microphonePermissionRequestDependencyDeclarations,
+    inputSchema: jsonSchema("computeruse.microphonePermissionRequest.input", {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+            target: {
+                type: "object",
+                additionalProperties: true,
+                properties: {
+                    targetApplication: { type: "string" },
+                    purpose: { type: "string" },
+                    deviceId: { type: "string" },
+                    mode: { type: "string", enum: ["session", "single-capture", "recording"] },
+                    requestedDurationMs: { type: "integer", minimum: 1 },
+                    maxDurationMs: { type: "integer", minimum: 1 },
+                },
+            },
+            targetApplication: { type: "string" },
+            purpose: { type: "string" },
+            deviceId: { type: "string" },
+            mode: { type: "string", enum: ["session", "single-capture", "recording"] },
+            requestedDurationMs: { type: "integer", minimum: 1 },
+            maxDurationMs: { type: "integer", minimum: 1 },
+            context: { type: "object", additionalProperties: true },
+            preferredProvider: { type: "string", enum: ["anthropic", "openai", "deepmind", "praxis-native"] },
+        },
+    }),
+    outputSchema: jsonSchema("computeruse.microphonePermissionRequest.output", {
+        type: "object",
+        additionalProperties: true,
+        required: ["kind", "target", "dispatch", "dryRun", "providerCalled", "runtimeEntry", "permissionEnvelope"],
+        properties: {
+            kind: { const: "agentCore.basicTool.computeruse.microphonePermissionRequest" },
+            target: { type: "object" },
+            dispatch: { type: "string", enum: ["dry-run", "runtime-computeruse"] },
+            dryRun: { type: "boolean" },
+            providerCalled: { type: "boolean" },
+            runtimeEntry: { type: "object" },
+            permissionEnvelope: { type: "object" },
+        },
+    }),
+    storagePolicy: {
+        storesMaterial: false,
+        storesResult: true,
+        storesAudit: true,
+        reusable: false,
+    },
+});
+export const microphonePermissionRequestHandler = createComputerUseCoreHandler(microphonePermissionRequestBaseToolDefinition, async (request) => {
+    const selection = selectMicrophonePermissionRequestPractice({
+        ...request.input,
+        executor: request.executor,
+    });
+    const auditMetadata = injectRuntimeInvocationMetadata(buildComputerUsePracticeAuditMetadata(selection), isRecord(request.input.context) && isRecord(request.input.context.auditMetadata)
+        ? request.input.context.auditMetadata
+        : undefined, request);
+    return executeMicrophonePermissionRequestCore({
+        ...request.input,
+        provider: selection.provider,
+        context: {
+            ...(isRecord(request.input.context) ? request.input.context : {}),
+            runtimeId: isRecord(request.input.context) && typeof request.input.context.runtimeId === "string"
+                ? request.input.context.runtimeId
+                : request.runtimeId,
+            sessionId: isRecord(request.input.context) && typeof request.input.context.sessionId === "string"
+                ? request.input.context.sessionId
+                : request.sessionId,
+            invocationId: isRecord(request.input.context) && typeof request.input.context.invocationId === "string"
+                ? request.input.context.invocationId
+                : request.toolCallId,
+            auditMetadata,
+        },
+    });
+});
+export { executeMicrophonePermissionRequestCore, microphonePermissionRequestDescriptor, planMicrophonePermissionRequest, };

package/dist/storagePool/baseToolStorage/computeruseBase/microphoneAccess/computeruse.microphonePermissionRequest/computeruse.microphonePermissionRequest.md

@@ -0,0 +1,136 @@
+---
+description: Request microphone access through the runtime-owned computer-use permission port.
+argument-hint: "{ purpose: string, target?: { targetApplication: string, deviceId?: string, mode?: 'session'|'single-capture'|'recording', requestedDurationMs?: number }, context?: { dryRun?: boolean, guard?: { accepted?: boolean, allowed?: boolean } } }"
+---
+
+# computeruse.microphonePermissionRequest
+
+## Use This Tool
+
+Use this tool when runtime/TAP has already decided that the next primitive action is to request a microphone permission lease from the active computer-use runtime.
+
+This is a low-level microphone access capability. It is not an audio recorder, transcription tool, omni routing step, OS permission UI implementation, browser controller, or fallback strategy.
+
+## Call Shape
+
+Call through `createBaseToolRegistry().lookupHandler("computeruse.microphonePermissionRequest").handler.invoke(...)` with a full `BaseToolInvokeRequest` envelope:
+
+```ts
+await handler.invoke({
+  toolCallId: "mic-permission-1",
+  runtimeId: "runtime-1",
+  sessionId: "session-1",
+  input: {
+    target: {
+      targetApplication: "voice-capture",
+      purpose: "capture a short voice note",
+      deviceId: "default-microphone",
+      mode: "single-capture",
+      requestedDurationMs: 30000,
+    },
+    context: {
+      dryRun: false,
+      guard: { accepted: true },
+      requestedScopes: ["tool:computeruse:microphone"],
+      allowedScopes: ["tool:computeruse:microphone"],
+    },
+  },
+  executor,
+});
+```
+
+The handler injects `runtimeId`, `sessionId`, and `toolCallId` into runtime invocation metadata before dispatching to storage/core.
+
+## Required Inputs
+
+- `target.targetApplication` or top-level `targetApplication`: application or workflow surface that needs microphone access.
+- `target.purpose` or top-level `purpose`: why microphone permission is requested.
+- `runtimeId`: required for audit and runtime correlation. The handler path may inject it from `BaseToolInvokeRequest.runtimeId` into `context.runtimeId`.
+- For real execution, `context.dryRun` must be `false` and `context.guard.allowed === true || context.guard.accepted === true`.
+- For real execution, runtime must provide `BaseToolExecutorPort.computeruse.requestPermission` through `executor.computeruse`.
+
+## Optional Inputs
+
+- `target.deviceId` or top-level `deviceId`: runtime-specific microphone id.
+- `target.mode` or top-level `mode`: `session`, `single-capture`, or `recording`; defaults to `session`.
+- `target.requestedDurationMs` or top-level `requestedDurationMs`: defaults to `60000`.
+- `target.maxDurationMs` or top-level `maxDurationMs`: defaults to `600000`.
+- `context.invocationId`: defaults to `toolCallId` when invoked through the handler.
+- `context.sessionId`: defaults to `BaseToolInvokeRequest.sessionId` when invoked through the handler.
+- `context.dryRun`: defaults to `true`.
+- `context.requestedScopes` and `context.allowedScopes`: optional scope check. Requested scopes not present in allowed scopes return `SCOPE_DENIED`.
+- `preferredProvider`: only selects practice metadata. It does not bypass runtime execution.
+
+## Runtime Behavior
+
+`core.ts` owns unknown-JSON validation, target normalization, duration validation, scope checks, dry-run planning, guard checks, provider-missing behavior, provider-failure mapping, and the public result envelope.
+
+Dry-run is the default. Dry-run returns a metadata-only permission plan and never calls a provider.
+
+Real execution dispatches only through `BaseToolExecutorPort.computeruse.requestPermission` with `resource: "microphone"`, `purpose`, optional `deviceId`, and runtime invocation metadata. If `executor.computeruse` or `requestPermission` is absent, the tool returns `PROVIDER_UNAVAILABLE`.
+
+Runtime owns OS prompts, app/device allowlists, microphone privacy boundaries, permission leases, persistent grants, revocation, platform adapters, and cleanup. The baseTool only declares the contract and normalizes the runtime result.
+
+Provider practice files are evidence and optional provider factories. They may describe Claude/Codex/Gemini lessons, but they do not turn browser-use, shell commands, media codecs, OS APIs, or provider SDKs into hidden baseTool behavior.
+
+Do not hide local shell, portal, audio capture CLI, browser automation, MCP, Playwright, Puppeteer, ffmpeg, PipeWire, OS automation, camera/microphone packages, or provider SDK dependencies inside this baseTool. Those belong in runtime adapters or TAP orchestration.
+
+## Returns
+
+- `output.kind`: `agentCore.basicTool.computeruse.microphonePermissionRequest`.
+- `output.dispatch`: `dry-run` or `runtime-computeruse`.
+- `output.target`: normalized `targetApplication`, `purpose`, optional `deviceId`, `mode`, and `requestedDurationMs`.
+- `output.providerCalled`: whether the runtime port was invoked.
+- `output.runtimeEntry.port`: `BaseToolExecutorPort.computeruse.requestPermission`.
+- `output.runtimeEntry.baseToolOwnsTapStrategy`: always `false`.
+- `output.permissionEnvelope`: dry-run metadata, or real `requested`, `granted`, and optional `leaseId`.
+- `output.providerMetadata`: public-safe metadata returned by runtime.
+- `metadata.audit`: invocation, practice, runtime, and dependency metadata added by the handler adapter.
+
+Stable public errors include `INVALID_REQUEST`, `INVALID_CONTEXT`, `INVALID_TARGET`, `MISSING_RUNTIME_ID`, `MISSING_TARGET_APPLICATION`, `MISSING_PURPOSE`, `INVALID_DEVICE_ID`, `INVALID_MODE`, `INVALID_DURATION`, `DURATION_LIMIT_EXCEEDED`, `SCOPE_DENIED`, `CONTRACT_REJECTED`, `GOVERNANCE_REJECTED`, `PROVIDER_UNAVAILABLE`, and `PROVIDER_FAILURE`.
+
+## Example
+
+```ts
+const lookup = createBaseToolRegistry().lookupHandler("computeruse.microphonePermissionRequest");
+if (!lookup.ok) throw new Error("handler missing");
+
+const result = await lookup.handler.invoke({
+  toolCallId: "mic-permission-1",
+  runtimeId: "runtime-1",
+  sessionId: "session-1",
+  executor: {
+    computeruse: {
+      async requestPermission(request) {
+        return {
+          ok: true,
+          output: {
+            granted: true,
+            leaseId: "lease:microphone:1",
+            metadata: { adapter: "fake-computeruse" },
+          },
+        };
+      },
+    },
+  },
+  input: {
+    target: {
+      targetApplication: "voice-capture",
+      purpose: "capture a short voice note",
+      mode: "single-capture",
+    },
+    context: {
+      dryRun: false,
+      guard: { accepted: true },
+    },
+  },
+});
+```
+
+## Avoid
+
+- Do not use this tool to record audio. It only requests microphone permission; recording belongs to recording tools and runtime media adapters.
+- Do not automatically call `omni.listenAudio`; artifact consumption belongs to TAP/agent or model-adapter layers.
+- Do not use this tool to choose workflow strategy, fallback to MCP, or decide whether a browser-specific interface exists. TAP/agent owns that composition.
+- Do not make `computeruseBase` a browser-use wrapper. Browser use is a TAP/MCP/runtime composition concern, not this tool's semantics.
+- Do not hide local shell, portal, audio, browser, media, device, model-provider, or filesystem dependencies inside `core.ts` or `bestPractice.ts`.

package/dist/storagePool/baseToolStorage/computeruseBase/microphoneAccess/computeruse.microphonePermissionRequest/core.d.ts

@@ -0,0 +1,126 @@
+export type MicrophonePermissionRequestBoundary = "input" | "contract" | "governance" | "scope" | "resource" | "provider";
+export type MicrophonePermissionRequestGate = {
+    accepted?: boolean;
+    allowed?: boolean;
+    reason?: string;
+};
+export type MicrophonePermissionRequestMode = "session" | "single-capture" | "recording";
+export type MicrophonePermissionRequestContext = {
+    runtimeId?: string;
+    sessionId?: string;
+    invocationId?: string;
+    dryRun?: boolean;
+    guard?: MicrophonePermissionRequestGate;
+    contract?: MicrophonePermissionRequestGate;
+    governance?: MicrophonePermissionRequestGate;
+    requestedScopes?: readonly string[];
+    allowedScopes?: readonly string[];
+    auditMetadata?: Readonly<Record<string, unknown>>;
+};
+export type MicrophonePermissionRequestTarget = {
+    targetApplication: string;
+    purpose: string;
+    deviceId?: string;
+    mode: MicrophonePermissionRequestMode;
+    requestedDurationMs: number;
+};
+export type MicrophonePermissionProviderRequest = {
+    operation: "computeruse.microphonePermissionRequest.request";
+    target: MicrophonePermissionRequestTarget;
+    context: {
+        runtimeId?: string;
+        sessionId?: string;
+        invocationId?: string;
+        auditMetadata?: Readonly<Record<string, unknown>>;
+    };
+};
+export type MicrophonePermissionProviderResult = {
+    granted: boolean;
+    leaseId?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type MicrophonePermissionProvider = (request: MicrophonePermissionProviderRequest) => Promise<MicrophonePermissionProviderResult> | MicrophonePermissionProviderResult;
+export type MicrophonePermissionRequestInput = {
+    target?: unknown;
+    context?: unknown;
+    targetApplication?: unknown;
+    purpose?: unknown;
+    deviceId?: unknown;
+    mode?: unknown;
+    requestedDurationMs?: unknown;
+    maxDurationMs?: unknown;
+    metadata?: unknown;
+    provider?: MicrophonePermissionProvider;
+};
+export type MicrophonePermissionRequestErrorCode = "INVALID_REQUEST" | "INVALID_CONTEXT" | "INVALID_TARGET" | "MISSING_RUNTIME_ID" | "MISSING_TARGET_APPLICATION" | "MISSING_PURPOSE" | "INVALID_DEVICE_ID" | "INVALID_MODE" | "INVALID_DURATION" | "DURATION_LIMIT_EXCEEDED" | "CONTRACT_REJECTED" | "GOVERNANCE_REJECTED" | "SCOPE_DENIED" | "PROVIDER_UNAVAILABLE" | "PROVIDER_FAILURE";
+export type MicrophonePermissionRequestError = {
+    code: MicrophonePermissionRequestErrorCode;
+    message: string;
+    boundary: MicrophonePermissionRequestBoundary;
+    publicSafe: true;
+    safeForRuntimeInspection: true;
+    internalDetailExposed: false;
+};
+export type MicrophonePermissionRequestAuditEvent = {
+    type: string;
+    toolId: "computeruse.microphonePermissionRequest";
+    invocationId: string;
+    dryRun: boolean;
+    deviceId?: string;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MicrophonePermissionRequestOutput = {
+    kind: "agentCore.basicTool.computeruse.microphonePermissionRequest";
+    target: MicrophonePermissionRequestTarget;
+    dispatch: "dry-run" | "runtime-computeruse";
+    dryRun: boolean;
+    providerCalled: boolean;
+    executionBlocked: boolean;
+    unsafeSideEffects: true;
+    permissionsRequired: readonly ["microphone:permission-request"];
+    requiresTapApproval: true;
+    acceptedScopes: readonly string[];
+    runtimeEntry: {
+        port: "BaseToolExecutorPort.computeruse.requestPermission";
+        operation: "computeruse.microphonePermissionRequest.request";
+        runtimeOwnsPermissionPrompt: true;
+        runtimeOwnsDeviceLease: true;
+        baseToolOwnsTapStrategy: false;
+    };
+    permissionEnvelope: {
+        resource: "microphone";
+        requested: boolean;
+        granted: boolean;
+        metadataOnly: boolean;
+        leaseId?: string;
+    };
+    providerMetadata?: Readonly<Record<string, unknown>>;
+};
+export type MicrophonePermissionRequestResult = {
+    ok: true;
+    toolId: "computeruse.microphonePermissionRequest";
+    output: MicrophonePermissionRequestOutput;
+    audit: readonly MicrophonePermissionRequestAuditEvent[];
+    events: readonly string[];
+} | {
+    ok: false;
+    toolId: "computeruse.microphonePermissionRequest";
+    error: MicrophonePermissionRequestError;
+    audit: readonly MicrophonePermissionRequestAuditEvent[];
+    events: readonly string[];
+};
+export declare const microphonePermissionRequestDescriptor: {
+    readonly toolId: "computeruse.microphonePermissionRequest";
+    readonly capability: "microphone-permission-request";
+    readonly route: "agent_executionEngine.basic_toolLayer.baseTools.computeruseBase.microphoneAccess";
+    readonly defaultDryRun: true;
+    readonly defaultMode: "session";
+    readonly defaultRequestedDurationMs: 60000;
+    readonly defaultMaxDurationMs: number;
+    readonly tapOwnsApproval: true;
+    readonly runtimeEntry: "BaseToolExecutorPort.computeruse.requestPermission";
+    readonly permissionsRequired: readonly ["microphone:permission-request"];
+    readonly unsafeSideEffects: true;
+};
+export declare function executeMicrophonePermissionRequest(request?: unknown): Promise<MicrophonePermissionRequestResult>;
+export declare function planMicrophonePermissionRequest(request?: unknown): Promise<MicrophonePermissionRequestResult>;