@pikku/core 0.12.78 → 0.12.80

package/src/pikku-state.ts

@@ -16,11 +16,22 @@ import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
 const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
 
+/**
+ * State is parked on `globalThis` under a registered symbol so separate copies
+ * of @pikku/core in one process share it. Typed once here rather than at each
+ * access.
+ */
+const stateHost = globalThis as unknown as {
+  [key: symbol]: Map<string, PikkuPackageState> | undefined
+}
+
 export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
-  if (!(globalThis as any)[PIKKU_STATE_KEY]) {
-    ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
+  let states = stateHost[PIKKU_STATE_KEY]
+  if (!states) {
+    states = new Map<string, PikkuPackageState>()
+    stateHost[PIKKU_STATE_KEY] = states
   }
-  return (globalThis as any)[PIKKU_STATE_KEY] as Map<string, PikkuPackageState>
+  return states
 }
 
 export const pikkuState = <
@@ -119,13 +130,13 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   middleware: {
     tagGroup: {},
     httpGroup: {},
-    global: [] as any,
+    global: [],
   },
   channelMiddleware: {
     tagGroup: {},
   },
   permissions: {
-    global: [] as any,
+    global: [],
   },
   misc: {
     errors: new Map(),
@@ -153,7 +164,7 @@ export const resetPikkuState = () => {
   // Error definitions come from module-import side effects that never re-run.
   const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
 
-  ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
+  stateHost[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
   initializePikkuState('__main__')
 
   if (existingErrors) {

package/src/public-surface.json

@@ -0,0 +1,578 @@
+{
+  ".": [
+    "AIProviderAuthError",
+    "AIProviderNotConfiguredError",
+    "AbandonedError",
+    "BadGatewayError",
+    "BadRequestError",
+    "ConflictError",
+    "ExpectationFailedError",
+    "ForbiddenError",
+    "GatewayTimeoutError",
+    "GoneError",
+    "HTTPVersionNotSupportedError",
+    "InternalServerError",
+    "InvalidMiddlewareWireError",
+    "InvalidOriginError",
+    "InvalidSessionError",
+    "LengthRequiredError",
+    "LocalEnvironmentOnlyError",
+    "LockedError",
+    "MaxComputeTimeReachedError",
+    "MethodNotAllowedError",
+    "MissingCredentialError",
+    "MissingSchemaError",
+    "MissingScopeError",
+    "MissingServiceError",
+    "MissingSessionError",
+    "NoopAuditService",
+    "NotAcceptableError",
+    "NotFoundError",
+    "NotImplementedError",
+    "PayloadTooLargeError",
+    "PaymentRequiredError",
+    "PikkuError",
+    "PikkuMissingMetaError",
+    "PikkuRequest",
+    "PreconditionFailedError",
+    "ProxyAuthenticationRequiredError",
+    "REDACTED",
+    "RangeNotSatisfiableError",
+    "ReadonlySessionError",
+    "RequestTimeoutError",
+    "SchedulerService",
+    "SecretAccessDeniedError",
+    "SecretCoercionError",
+    "SecretHostNotAllowedError",
+    "ServiceUnavailableError",
+    "TooManyRequestsError",
+    "URITooLongError",
+    "UnauthorizedError",
+    "UnprocessableContentError",
+    "UnsupportedMediaTypeError",
+    "addGlobalPermission",
+    "addTagMiddleware",
+    "assertSecretAllowedForHost",
+    "beginChanges",
+    "checkAuthPermissions",
+    "clearPikkuRuntimeState",
+    "createGraph",
+    "createInvocationAudit",
+    "createSecretValue",
+    "fetch",
+    "formatVersionedId",
+    "getAbortScope",
+    "getAllFunctionNames",
+    "getRelativeTimeOffsetFromNow",
+    "hasScopes",
+    "hashToken",
+    "isExpectedError",
+    "isSecretValue",
+    "isSerializable",
+    "isVersionedId",
+    "parseDurationString",
+    "parseVersionedId",
+    "pikkuAIMiddleware",
+    "pikkuApprovalDescription",
+    "pikkuAuth",
+    "pikkuCLIRender",
+    "pikkuChannelMiddleware",
+    "pikkuChannelMiddlewareFactory",
+    "pikkuMiddleware",
+    "pikkuMiddlewareFactory",
+    "pikkuPermission",
+    "pikkuPermissionFactory",
+    "pikkuServerLifecycle",
+    "resolveAuditConfig",
+    "resolveAuditUserIdentityFromWire",
+    "runInAbortScope",
+    "runMiddleware",
+    "stopSingletonServices",
+    "unsafeAsHashed",
+    "unsafeAsSealed",
+    "unsafeAsWrapped",
+    "verifyScopes",
+    "wireAddon",
+    "wireRemoteAddon",
+    "withoutSecrets"
+  ],
+  "./middleware": [
+    "addGlobalMiddleware",
+    "addGlobalPermission",
+    "addMiddleware",
+    "addTagMiddleware",
+    "authAPIKey",
+    "authBearer",
+    "authCookie",
+    "cors",
+    "pikkuRemoteAuthMiddleware",
+    "runMiddleware",
+    "telemetryInner",
+    "telemetryOuter"
+  ],
+  "./function": [
+    "addFunction",
+    "getAllFunctionNames",
+    "pikkuApprovalDescription",
+    "pikkuAuth",
+    "pikkuPermission",
+    "pikkuPermissionFactory"
+  ],
+  "./channel": [
+    "CHANNEL_RPC_PENDING",
+    "CHANNEL_RPC_REQUEST",
+    "CHANNEL_RPC_RESPONSE",
+    "ChannelDeploymentService",
+    "ChannelRPCError",
+    "ChannelRPCRegistry",
+    "ChannelStore",
+    "EventHubStore",
+    "PikkuAbstractChannelHandler",
+    "addChannelMiddleware",
+    "channelRemote",
+    "combineChannelMiddleware",
+    "createChannelRPCInputValidator",
+    "createChannelRPCResponder",
+    "createChannelRPCResultValidator",
+    "defineChannelRoutes",
+    "getChannelHostRPC",
+    "handleChannelRPCResponse",
+    "isChannelRPCPending",
+    "isChannelRPCRequest",
+    "isChannelRPCResponse",
+    "logChannels",
+    "openChannel",
+    "releaseChannelHostRPC",
+    "resolveCapability",
+    "unsupportedChannelRemote",
+    "wireChannel",
+    "wrapChannelWithMiddleware"
+  ],
+  "./workflow": [
+    "DEFAULT_STEP_RETRIES",
+    "PikkuWorkflowService",
+    "SCENARIO_SURFACES",
+    "WorkflowApprovalResolvedError",
+    "WorkflowCancelledException",
+    "WorkflowDispatchException",
+    "WorkflowNotFoundError",
+    "WorkflowRunForbiddenError",
+    "WorkflowRunNotFoundError",
+    "WorkflowStepFunctionMismatchError",
+    "WorkflowSuspendedException",
+    "addFeature",
+    "addWorkflow",
+    "assertWorkflowRunOwner",
+    "buildRunTimeline",
+    "composeStepProse",
+    "createCookieJar",
+    "deriveInvocationId",
+    "isRef",
+    "pikkuWorkflowGraph",
+    "pikkuWorkflowOrchestratorFunc",
+    "pikkuWorkflowSleeperFunc",
+    "pikkuWorkflowWorkerFunc",
+    "pollUntil",
+    "reconstructFinalState",
+    "reconstructStateAt",
+    "renderStepTemplate",
+    "requireActor",
+    "requireScenarioEnv",
+    "resolveFeatureScenarios",
+    "resolveScenarioSurfaces",
+    "template",
+    "uuidv5",
+    "witnessesAgree"
+  ],
+  "./scenario": [
+    "PikkuScenarioService",
+    "ScenarioBrowserActorRequired",
+    "ScenarioBrowserUnavailable",
+    "ScenarioHookError",
+    "ScenarioNoSurfaceBinding",
+    "ScenarioNoWitness",
+    "ScenarioWitnessDisagreement",
+    "createScenarioRunner"
+  ],
+  "./workflow/timeline": [
+    "buildRunTimeline",
+    "reconstructFinalState",
+    "reconstructStateAt"
+  ],
+  "./workflow/types": [],
+  "./actor-flow": ["runConversation"],
+  "./virtual-user": [
+    "DISPOSITIONS",
+    "IntentStack",
+    "PRODUCTION_DISPOSITION",
+    "catalogueClassification",
+    "catalogueIndex",
+    "catalogueLookup",
+    "createRng",
+    "deriveCatalogue",
+    "deriveIntents",
+    "describeEntry",
+    "dispositionProfile",
+    "intentsForPersona",
+    "isReadOnly",
+    "personaScopes",
+    "personaVirtualUserTarget",
+    "prepareVirtualUserRun",
+    "reachableAgents",
+    "reachableCatalogue",
+    "rememberIds",
+    "renderCatalogue",
+    "runVirtualUser",
+    "unreachableCatalogue"
+  ],
+  "./channel/local": [
+    "LocalEventHubService",
+    "PikkuLocalChannelHandler",
+    "runLocalChannel"
+  ],
+  "./channel/serverless": [
+    "runChannelConnect",
+    "runChannelDisconnect",
+    "runChannelMessage"
+  ],
+  "./http": [
+    "DEFAULT_MAX_BODY_SIZE",
+    "PikkuFetchHTTPRequest",
+    "PikkuFetchHTTPResponse",
+    "addHTTPMiddleware",
+    "applyWebResponse",
+    "defineHTTPRoutes",
+    "fetch",
+    "fetchData",
+    "logRoutes",
+    "toWebRequest",
+    "wireHTTP",
+    "wireHTTPRoutes"
+  ],
+  "./remote": ["buildRemoteHeaders"],
+  "./queue": [
+    "QUEUE_IDENTITY_CLAIM_VERSION",
+    "QUEUE_IDENTITY_INFO",
+    "QUEUE_IDENTITY_SECRET_NAME",
+    "QueueJobDiscardedError",
+    "QueueJobFailedError",
+    "SignedQueueService",
+    "getQueueIdentitySecret",
+    "getQueueWorkers",
+    "registerQueueWorkers",
+    "removeQueueWorker",
+    "resolveQueueJobIdentity",
+    "runQueueJob",
+    "signQueueIdentity",
+    "validateWorkerConfig",
+    "verifyQueueIdentity",
+    "wireQueueWorker"
+  ],
+  "./scheduler": [
+    "getScheduledTasks",
+    "logSchedulers",
+    "runScheduledTask",
+    "wireScheduler"
+  ],
+  "./trigger": ["PikkuTriggerService", "wireTrigger", "wireTriggerSource"],
+  "./rpc": [
+    "PikkuRPCService",
+    "RPCNotFoundError",
+    "RemoteAddonAuthError",
+    "RemoteAddonConfigError",
+    "RemoteAddonRequestError",
+    "resolveRemoteAddonToken",
+    "rpcService",
+    "wireAddon",
+    "wireRemoteAddon"
+  ],
+  "./safe-fetch": [
+    "assertFetchableUrl",
+    "isPrivateHost",
+    "safeFetch",
+    "setDefaultHostResolver"
+  ],
+  "./node-host-resolver": ["installNodeHostResolver", "nodeHostResolver"],
+  "./mcp": [
+    "MCPEndpointRegistry",
+    "MCPError",
+    "getMCPPromptsMeta",
+    "getMCPResourcesMeta",
+    "getMCPToolsMeta",
+    "runMCPPrompt",
+    "runMCPResource",
+    "runMCPTool",
+    "wireMCPPrompt",
+    "wireMCPResource"
+  ],
+  "./ai-agent": [
+    "AgentInterruptedError",
+    "NoSpeechDetectedError",
+    "SPOKEN_TRANSCRIPT",
+    "SPOKEN_TURN",
+    "ToolApprovalRequired",
+    "ToolCredentialRequired",
+    "addAIAgent",
+    "agent",
+    "agentApprove",
+    "agentInterrupt",
+    "agentResume",
+    "agentStream",
+    "approveAIAgent",
+    "awaitPendingInterruptNote",
+    "canAccessThread",
+    "getAIAgents",
+    "getAIAgentsMeta",
+    "getInFlightTools",
+    "interruptAIAgent",
+    "isAbortError",
+    "isOwnedByPrincipal",
+    "isRunInterruptible",
+    "persistOrphanedToolResults",
+    "readsAsNonSpeech",
+    "registerInterruptibleRun",
+    "resumeAIAgent",
+    "resumeAIAgentSync",
+    "runAIAgent",
+    "sessionPrincipals",
+    "signalRunInterrupt",
+    "streamAIAgent",
+    "threadOwnerConstraint",
+    "trackInterruptNote",
+    "trackToolExecution",
+    "unspeakableScripts",
+    "voiceForText",
+    "voiceInput",
+    "voiceOutput",
+    "wrapChannelWithAGUI"
+  ],
+  "./gateway": [
+    "createListenerMessageHandler",
+    "resolveGatewayAdapter",
+    "wireGateway"
+  ],
+  "./cli": [
+    "CLIError",
+    "defineCLICommands",
+    "executeCLI",
+    "generateCommandHelp",
+    "parseCLIArguments",
+    "pikkuCLIRender",
+    "runCLICommand",
+    "wireCLI"
+  ],
+  "./cli/command-parser": ["generateCommandHelp", "parseCLIArguments"],
+  "./cli/channel": [
+    "APPROVAL_FLAGS",
+    "approverForMode",
+    "createTerminalApprover",
+    "executeCLIViaChannel",
+    "executeRawCLIViaChannel",
+    "handleRawCLI",
+    "takeApprovalFlags"
+  ],
+  "./node": [],
+  "./credential": [
+    "defineCredential",
+    "validateAndBuildCredentialDefinitionsMeta"
+  ],
+  "./scope": [
+    "defineScope",
+    "flattenScopeDefinitions",
+    "validateAndBuildScopeDefinitionsMeta"
+  ],
+  "./role": [
+    "defineSystemRole",
+    "flattenSystemRoleDefinitions",
+    "validateAndBuildSystemRoleDefinitionsMeta"
+  ],
+  "./persona": [
+    "HttpPersona",
+    "allowedLinks",
+    "applyMailboxAllowlist",
+    "createHttpPersonas",
+    "definePersonas",
+    "isAllowedSender",
+    "isRunnablePersona",
+    "personaEmail",
+    "personaEmailLabel",
+    "personaEmails",
+    "personaEnvironmentErrors",
+    "personaEnvironmentRefusal",
+    "postScenarioJson",
+    "readScenarioHttpResponse",
+    "resolvePersonaEnvironments",
+    "roleMismatchMessage",
+    "runnablePersonas",
+    "validateAndBuildPersonasMeta",
+    "verifyPersonaRoles"
+  ],
+  "./secret": ["defineSecret", "validateAndBuildSecretDefinitionsMeta"],
+  "./variable": ["defineVariable", "validateAndBuildVariableDefinitionsMeta"],
+  "./oauth2": [],
+  "./errors": [
+    "AIProviderAuthError",
+    "AIProviderNotConfiguredError",
+    "BadGatewayError",
+    "BadRequestError",
+    "ConflictError",
+    "ExpectationFailedError",
+    "ForbiddenError",
+    "GatewayTimeoutError",
+    "GoneError",
+    "HTTPVersionNotSupportedError",
+    "InternalServerError",
+    "InvalidMiddlewareWireError",
+    "InvalidOriginError",
+    "InvalidSessionError",
+    "LengthRequiredError",
+    "LocalEnvironmentOnlyError",
+    "LockedError",
+    "MaxComputeTimeReachedError",
+    "MethodNotAllowedError",
+    "MissingCredentialError",
+    "MissingSchemaError",
+    "MissingScopeError",
+    "MissingServiceError",
+    "MissingSessionError",
+    "NotAcceptableError",
+    "NotFoundError",
+    "NotImplementedError",
+    "PayloadTooLargeError",
+    "PaymentRequiredError",
+    "PikkuError",
+    "PikkuMissingMetaError",
+    "PreconditionFailedError",
+    "ProxyAuthenticationRequiredError",
+    "RangeNotSatisfiableError",
+    "ReadonlySessionError",
+    "RequestTimeoutError",
+    "ServiceUnavailableError",
+    "SystemRoleImmutableError",
+    "SystemRoleShadowedError",
+    "TooManyRequestsError",
+    "URITooLongError",
+    "UnauthorizedError",
+    "UnprocessableContentError",
+    "UnsupportedMediaTypeError",
+    "WeakKeyMaterialError",
+    "addError",
+    "addErrors"
+  ],
+  "./services": [
+    "ConsoleLogger",
+    "DEFAULT_WEBHOOK_RETRIES",
+    "DEFAULT_WEBHOOK_SIGNATURE_HEADER",
+    "InMemoryAIRunStateService",
+    "InMemoryQueueService",
+    "InMemorySessionStore",
+    "InMemoryTriggerService",
+    "InMemoryWorkflowService",
+    "JsonConsoleLogger",
+    "LocalCredentialService",
+    "LocalEmailService",
+    "LocalGatewayService",
+    "LocalSecretService",
+    "LocalVariablesService",
+    "LogLevel",
+    "NoopAuditService",
+    "PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME",
+    "PikkuCredentialWireService",
+    "PikkuSessionService",
+    "QueueWebhookService",
+    "ScopedSecretService",
+    "SecretHostNotAllowedError",
+    "StubTracker",
+    "TypedCredentialService",
+    "TypedSecretService",
+    "TypedVariablesService",
+    "WebhookService",
+    "assertRoleIsMutable",
+    "assertRoleNameAvailable",
+    "assertSecretAllowedForHost",
+    "createFunctionSessionWireProps",
+    "createInvocationAudit",
+    "createMiddlewareCredentialWireProps",
+    "createMiddlewareSessionWireProps",
+    "createStubProxy",
+    "createWireServicesCredentialWireProps",
+    "getStubTracker",
+    "isTestRun",
+    "pikkuWebhookWorkerFunc",
+    "resolveAuditConfig",
+    "resolveAuditUserIdentityFromWire",
+    "roleLockReason",
+    "spy",
+    "stub"
+  ],
+  "./services/local-meta": ["LocalMetaService"],
+  "./services/v8-coverage": ["V8CoverageService"],
+  "./services/istanbul-coverage": ["IstanbulCoverageService"],
+  "./services/local-content": ["LocalContent", "signedContentPath"],
+  "./services/local-content-request-handler": [
+    "createLocalContentRequestHandler",
+    "verifySignedContentRequest"
+  ],
+  "./services/temporary-file-service": [
+    "TemporaryFileInstance",
+    "TemporaryFileService"
+  ],
+  "./crypto-utils": [
+    "MIN_KEY_MATERIAL_LENGTH",
+    "REMOTE_SESSION_INFO",
+    "assertStrongKeyMaterial",
+    "decodeBase64UrlText",
+    "decryptJSON",
+    "decryptWithKeyMaterial",
+    "deriveKEK",
+    "encodeBase64UrlText",
+    "encryptJSON",
+    "encryptWithKeyMaterial",
+    "envelopeDecrypt",
+    "envelopeEncrypt",
+    "envelopeRewrap",
+    "generateDEK",
+    "generateKEKSalt",
+    "signWithKeyMaterial",
+    "unwrapDEK",
+    "verifyWithKeyMaterial",
+    "wrapDEK"
+  ],
+  "./hmac": ["hmacSha256Hex", "timingSafeStringEqual"],
+  "./ecosystem": [
+    "addFunction",
+    "addGlobalMiddleware",
+    "addMiddleware",
+    "getAllPackageStates",
+    "getCreateWireServices",
+    "getSingletonServices",
+    "httpRouter",
+    "pikkuState",
+    "resetPikkuState",
+    "runPikkuFunc",
+    "setSingletonServices"
+  ],
+  "./internal": [
+    "addFunction",
+    "addGlobalMiddleware",
+    "addMiddleware",
+    "getAllPackageStates",
+    "getCreateWireServices",
+    "getSingletonServices",
+    "httpRouter",
+    "pikkuState",
+    "resetPikkuState",
+    "runPikkuFunc",
+    "setSingletonServices"
+  ],
+  "./schema": [
+    "addSchema",
+    "applyDefaultsFromSchema",
+    "coerceTopLevelDataFromSchema",
+    "compileAllSchemas",
+    "getSchema",
+    "validateSchema"
+  ],
+  "./testing": ["defineServiceTests"],
+  "./dev": ["pikkuDevReloader", "reconcileAddonRegistry", "reloadGeneratedMeta"]
+}

package/src/public-surface.json.README

@@ -0,0 +1,25 @@
+`public-surface.json` pins every runtime export reachable through a
+`package.json` `exports` subpath. `public-surface.test.ts` fails when the two
+disagree, so widening the API is a visible diff rather than a side effect of an
+`export *`.
+
+Types are not pinned: they are erased before the test can enumerate them.
+
+Regenerate after an intentional change, from `packages/core`:
+
+```bash
+cat > src/__gen-surface.mts <<'EOF'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const pkg = JSON.parse(readFileSync('package.json', 'utf-8'))
+const surface: Record<string, string[]> = {}
+for (const [sub, dist] of Object.entries(pkg.exports as Record<string, string>)) {
+  const src = pathToFileURL(resolve(dist.replace('./dist/', './src/'))).href
+  surface[sub] = Object.keys(await import(src)).sort()
+}
+writeFileSync('src/public-surface.json', JSON.stringify(surface, null, 2) + '\n')
+EOF
+npx tsx src/__gen-surface.mts && rm src/__gen-surface.mts
+```