pomerado 0.1.2 → 0.2.0

package/dist/typescript/src/runtime/provider-metadata.d.ts

@@ -1,14 +1,15 @@
 export type BrowserMode = "headless" | "headful" | "headful-gpu";
 export type RetainedProviderStage = "profile_decode" | "connection_decode" | "connection_duplicate_fields" | "timeline_decode" | "browser_session_mismatch" | "login_browser_decode" | "login_already_running" | "login_response_decode" | "submit_state"
-/** Kernel answered the submission `accepted: false`. */
+/** The provider answered the submission `accepted: false`. */
  | "submit_rejected" | "submit_response_decode" | "cleanup_identity_decode";
 export type RetainedProviderSchemaField = "profile" | "profile.id" | "profile_save_changes" | "stealth" | "browser.stealth" | "other";
 export type RetainedProviderCode = "Unavailable" | "InvalidConfiguration" | "ProxyUnavailable" | "AllocationUncertain"
-/** Kernel answered the create with a definite refusal, so no browser exists. */
+/** The provider answered the create with a definite refusal, so no browser exists. */
  | "AllocationRejected" | "StopUnconfirmed" | "UnexpectedBrowserState" | "StorageUnavailable" | "BindingNotFound";
-/** Proxy failure codes retained in sign-in diagnostics. */
-export type RetainedProxyError = "upstream_timeout" | "provider_unreachable" | "upstream_connect_failed" | "upstream_dns_failure" | "origin_tls_timeout" | "restricted_route_unavailable" | "destination_route_unavailable" | "proxy_unavailable" | "origin_response_incomplete" | "provider_rejected" | "provider_blacklisted" | "destination_blocked" | "mitm_certificate" | "mitm_tls" | "mitm_tls_rejected" | "mitm_connect" | "mitm_stream" | "mitm_io" | "mitm_timeout" | "mitm_canceled" | "mitm_upstream_proxy" | "mitm_h1" | "mitm_request_invalid" | "mitm_other" | "proxy_forbidden" | "proxy_auth_required" | "proxy_rate_limited" | "other";
-export type ProxySwitchSummary = {
+/** Network failure codes a host retains in sign-in diagnostics, as its provider reported them. */
+export type RetainedNetworkError = "upstream_timeout" | "provider_unreachable" | "upstream_connect_failed" | "upstream_dns_failure" | "origin_tls_timeout" | "restricted_route_unavailable" | "destination_route_unavailable" | "proxy_unavailable" | "origin_response_incomplete" | "provider_rejected" | "provider_blacklisted" | "destination_blocked" | "mitm_certificate" | "mitm_tls" | "mitm_tls_rejected" | "mitm_connect" | "mitm_stream" | "mitm_io" | "mitm_timeout" | "mitm_canceled" | "mitm_upstream_proxy" | "mitm_h1" | "mitm_request_invalid" | "mitm_other" | "proxy_forbidden" | "proxy_auth_required" | "proxy_rate_limited" | "other";
+/** How the host replaced a browser after a failure, as the agent sees it. */
+export type BrowserRecoverySummary = {
     readonly kind: "switched";
     readonly egress: "proxy" | "direct";
     readonly cause: string;
@@ -16,7 +17,7 @@ export type ProxySwitchSummary = {
     readonly possiblySent: boolean;
     readonly inFlightPossiblySent: true;
     readonly repeated: false;
-    /** The browser's cookies, cache and site storage were cleared for the new proxy. */
+    /** The browser's cookies, cache and site storage were cleared for the replacement. */
     readonly stateCleared: true;
     /** Set when the clear ended the site's signed-in session. */
     readonly signIn?: "again_once" | "unavailable";

package/dist/typescript/src/runtime/script-input.d.ts

@@ -32,7 +32,7 @@ export declare const ScriptQuestionDeclaration: Schema.Union<[Schema.Struct<{
     prompt: Schema.filter<Schema.filter<typeof Schema.String>>;
 }>]>;
 export type ScriptQuestionDeclaration = typeof ScriptQuestionDeclaration.Type;
-export declare const ScriptQuestionDeclarations: Schema.Record$<Schema.filter<typeof Schema.String>, Schema.Union<[Schema.Struct<{
+export declare const ScriptQuestionDeclarations: Schema.transform<Schema.filter<typeof Schema.Unknown>, Schema.Record$<Schema.filter<typeof Schema.String>, Schema.Union<[Schema.Struct<{
     type: Schema.Literal<["choice"]>;
     prompt: Schema.filter<Schema.filter<typeof Schema.String>>;
     allowOther: Schema.optional<typeof Schema.Boolean>;
@@ -61,7 +61,7 @@ export declare const ScriptQuestionDeclarations: Schema.Record$<Schema.filter<ty
     maxLength: Schema.optional<Schema.filter<typeof Schema.Int>>;
 }>, Schema.Struct<{
     prompt: Schema.filter<Schema.filter<typeof Schema.String>>;
-}>]>>;
+}>]>>>;
 export type ScriptQuestionDeclarations = Readonly<Record<string, ScriptQuestionDeclaration>>;
 /** One option the page offers now. */
 export declare const ScriptOption: Schema.Struct<{

package/dist/typescript/src/runtime/script-input.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { Context, Data, Effect, Either, Schema } from "effect";
-import { ConfirmQuestion, InputRequest, QuestionId, SecretQuestion, TextQuestion, validateAnswer, } from "./input-request.js";
+import { Context, Data, Effect, Either, Schema, SchemaAST } from "effect";
+import { ConfirmQuestion, InputRequest, QuestionId, questionIdPattern, SecretQuestion, TextQuestion, validateAnswer, } from "./input-request.js";
 /**
  * A script asks its caller through the one input request (source `script`). It declares each
  * question once in its contract, so the publication review reads every prompt, and passes the
@@ -35,10 +35,20 @@ export const ScriptQuestionDeclaration = Schema.Union(Schema.Struct({
 }), 
 // The pre-unification shape, `{ prompt }`, kept for published revisions: a single choice.
 Schema.Struct({ prompt: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(500)) }));
-export const ScriptQuestionDeclarations = Schema.Record({
+const QuestionDeclarations = Schema.Record({
     key: QuestionId,
     value: ScriptQuestionDeclaration,
 });
+export const ScriptQuestionDeclarations = Schema.Unknown.pipe(
+// Check original keys before record construction can discard __proto__ or another invalid id.
+Schema.filter((questions) => typeof questions !== "object" ||
+    questions === null ||
+    Object.keys(questions).every((id) => questionIdPattern.test(id)), {
+    message: () => "question ids must start with a lowercase letter and contain only lowercase letters, digits, or underscores (up to 64 characters)",
+}), Schema.compose(QuestionDeclarations)).annotations({
+    // Schema generation still describes the declarations rather than the unvalidated input.
+    [SchemaAST.SurrogateAnnotationId]: QuestionDeclarations.ast,
+});
 /** One option the page offers now. */
 export const ScriptOption = Schema.Struct({
     /** What `ask` returns when the caller picks it. It never leaves the sandbox. */

package/dist/typescript/src/standalone/mcp-cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
@@ -98,6 +99,16 @@ export const startMcpCli = (args = process.argv.slice(2), options = {}) => {
         },
     });
 };
-if (process.argv[1] !== undefined &&
-    pathToFileURL(resolve(process.argv[1])).href === import.meta.url)
+/** npm links a bin to this file, so the entry path counts once its links are resolved. */
+const isEntrypoint = (path) => {
+    if (path === undefined)
+        return false;
+    try {
+        return pathToFileURL(realpathSync(path)).href === import.meta.url;
+    }
+    catch {
+        return false;
+    }
+};
+if (isEntrypoint(process.argv[1]))
     startMcpCli();

package/dist/typescript/src/standalone/mcp-package.js

@@ -6,12 +6,29 @@ import { localFilePath, localPromise, localError, localRelativePath, } from "../
 import { Deployment, writeArtifact } from "./artifact-files.js";
 const launcher = `import { fileURLToPath } from 'node:url';
 const runtime = process.argv[2];
-if (!runtime) throw new Error('Start this integration using its generated Codex configuration.');
+if (!runtime) throw new Error('Start this integration with the command and arguments in its mcp.json.');
 const { startMcpCli } = await import(runtime);
 startMcpCli(['serve', '--artifact', fileURLToPath(new URL('.', import.meta.url))]);
 `;
 const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
-const reserved = new Set(["deployment.json", "mcp.mjs", "codex-mcp.toml", "readme.md"]);
+/**
+ * Top-level names authored source may not use, compared in lower case. They cover the packaging
+ * files, the TOML that 0.1.2 wrote and its docs told users to copy into Codex, and the project
+ * config an MCP client might load from this folder.
+ */
+const reserved = new Set([
+    "deployment.json",
+    "mcp.mjs",
+    "mcp.json",
+    "readme.md",
+    "codex-mcp.toml",
+    ".mcp.json",
+    ".vscode",
+    ".cursor",
+    ".codex",
+    ".gemini",
+    ".claude",
+]);
 /** Only the local operator's configuration chooses the root; tool arguments choose one slug. */
 export const prepareIntegration = (options) => Effect.gen(function* () {
     const deployment = yield* Schema.decodeUnknown(Deployment)({
@@ -46,37 +63,70 @@ export const prepareIntegration = (options) => Effect.gen(function* () {
         yield* writeArtifact(directory, artifact);
         const workspace = yield* createLocalWorkspace({ root: directory });
         const launcherPath = join(directory, "mcp.mjs");
-        const configPath = join(directory, "codex-mcp.toml");
+        const configPath = join(directory, "mcp.json");
         const runtime = new URL("./mcp-cli.js", import.meta.url).href;
-        const configuration = `[mcp_servers.${deployment.name}]
-command = ${JSON.stringify(process.execPath)}
-args = ${JSON.stringify([launcherPath, runtime])}
-env_vars = ["OPENAI_API_KEY"]
-`;
+        const args = [launcherPath, runtime];
+        const configuration = {
+            mcpServers: { [deployment.name]: { command: process.execPath, args } },
+        };
+        const command = [process.execPath, ...args].map(shellQuote).join(" ");
         yield* workspace.write("deployment.json", `${JSON.stringify(deployment, null, 2)}\n`);
         yield* workspace.write("mcp.mjs", launcher);
-        yield* workspace.write("codex-mcp.toml", configuration);
+        yield* workspace.write("mcp.json", `${JSON.stringify(configuration, null, 2)}\n`);
         yield* workspace.write("README.md", `# ${deployment.name}
 
-This integration is hosted locally over MCP stdio. Add the command and arguments from
-codex-mcp.toml to your Codex configuration (~/.codex/config.toml). Alternatively, register it with:
+This integration runs on your computer as a local MCP stdio server. mcp.json holds its server
+entry in the standard mcpServers format. The entry starts your Node with this directory's
+launcher and your installed Pomerado runtime.
+
+## Add it to your MCP client
+
+- Claude Code passes its own environment to the server.
+
+  \`\`\`sh
+  claude mcp add ${deployment.name} -- ${command}
+  \`\`\`
+
+- Codex passes servers only a short list of environment variables. After adding the server, put
+  \`env_vars = ["OPENAI_API_KEY"]\` under \`[mcp_servers.${deployment.name}]\` in
+  ~/.codex/config.toml, or $CODEX_HOME/config.toml when CODEX_HOME is set.
+
+  \`\`\`sh
+  codex mcp add ${deployment.name} -- ${command}
+  \`\`\`
 
-\`\`\`sh
-codex mcp add ${deployment.name} -- ${shellQuote(process.execPath)} ${shellQuote(launcherPath)} ${shellQuote(runtime)}
-\`\`\`
+- Gemini CLI hides variables named like keys from servers. The -e flag below passes
+  OPENAI_API_KEY by reference, so the settings file holds no key.
+
+  \`\`\`sh
+  gemini mcp add -e 'OPENAI_API_KEY=$OPENAI_API_KEY' ${deployment.name} ${command}
+  \`\`\`
+
+- Cursor, VS Code, Claude Desktop and other clients that read an mcpServers JSON file take the
+  entry from mcp.json. In Cursor, add \`"env": { "OPENAI_API_KEY": "\${env:OPENAI_API_KEY}" }\`
+  to it.
+
+## Model key
+
+The server needs OPENAI_API_KEY in its environment, because Guardian reviews every run. Model
+requests go to the configured provider. This directory and mcp.json hold no key. Give the key to
+the server through your client's environment settings, never through chat.
+
+## Call it
 
 Call ${deployment.name} with its discovered input schema. Its URL, intent, authority and
-authentication origins are pinned in deployment.json. Jobs and questions continue through
-get_job, provide_input and cancel_job; polling never resubmits an operation.
+authentication origins are pinned in deployment.json. A call that needs an answer or more time
+returns a job ID. Continue that job with get_job, provide_input and cancel_job. Polling never
+resubmits an operation.
+
+Answers sent through provide_input are visible to your MCP client and its model provider.
+Restarting the server loses live jobs.
 
-The launcher uses the shared installed Pomerado runtime, minter/Guardian dependencies and
-local Chromium. Configured model providers receive model requests. The TOML forwards
-OPENAI_API_KEY from Codex's environment. Supply provider keys in
-the server's environment; this directory and its configuration contain no keys. Answers sent
-through provide_input are visible to the MCP client and its model. Restarting loses live jobs.
+## Paths
 
-The launcher source is portable. The local configuration references your current Node and
-runtime installation; update those paths if you move either installation or this directory.
+The launcher uses your installed Pomerado runtime, its minter and Guardian dependencies, and
+local Chromium. The launcher source is portable. mcp.json names your current Node and Pomerado
+installation. Update those paths if you move either installation or this directory.
 `);
         completed = true;
         return { directory, configPath, launcherPath };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "pomerado",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Pomerado's integration minter and Guardian with local compute and native Playwright",
   "type": "module",
-  "license": "AGPL-3.0-only",
+  "license": "MIT",
   "homepage": "https://pomerado.ai",
   "repository": {
     "type": "git",
@@ -595,6 +595,7 @@
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "third-party/codex/LICENSE",