@pikku/core 0.12.122 → 0.12.123

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## 0.12.123
+
+### Patch Changes
+
+- 50b59a3: Keep the agent runtime out of deployment units that hold no agent.
+
+  `ContextAwareRPCService.agent` imported `agent-rpc.ts` directly, and every unit
+  reaches that class through the function runner, so the agent runner, stream,
+  memory and AGUI modules were pinned into every bundle — 51.8 KB raw / 15.7 KB
+  gzip a unit. The facade is now resolved through state, registered by
+  `@pikku/core/agent` on import, so only a unit that actually holds an agent
+  bundles it. A unit that reaches `rpc.agent` without importing the agent entry
+  point throws rather than silently pulling the runtime back in.
+
+- 2b946e9: fix(dev): keep `import.meta` pointing at the real file in the hot-reload runner
+
+  The dev module runner transforms each user file to `cjs` before compiling it,
+  and esbuild's `cjs` output rewrites `import.meta` to an empty object. Any module
+  that resolves its own neighbours through `createRequire(import.meta.url)` —
+  sharp, onnxruntime-node, essentially every package with a native binding —
+  therefore received `undefined` and failed with `Cannot find module
+'@img/sharp-linux-x64/sharp.node' from ''`. sharp's own loader filters on
+  `MODULE_NOT_FOUND` and reports its generic "could not load the sharp module"
+  instead, so the empty referrer never appears in the error the developer sees.
+
+  `import.meta.url`, `import.meta.filename` and `import.meta.dirname` are now
+  defined to the file being run, so resolution behaves as it does under Node's
+  ESM loader.
+
+- bc488cf: fix(inspector): an explicit `auth: false` declares an exposed sessionless function public, so PKU574 no longer warns about it
+
+  A genuinely public endpoint — a published programme, a health check — had no
+  honest way to quiet PKU574: the only options were an always-true permission or
+  `permissionsInBody: true`, both of which claim a gate that does not exist. The
+  inspector now records `auth` on function meta exactly as written instead of
+  dropping `false`, and the check treats an explicit `auth: false` as the author
+  declaring the function public on purpose. A sessionless function that leaves
+  `auth` out still warns.
+
 ## 0.12.122
 
 ### Patch Changes

package/dist/dev/module-runner.js

@@ -68,6 +68,15 @@ const evaluateModule = (absPath, cache) => {
         loader: loaderFor(absPath),
         format: 'cjs',
         sourcefile: absPath,
+        // `cjs` output rewrites `import.meta` to an empty object, so a module
+        // that resolves its own neighbours through `createRequire(import.meta.url)`
+        // -- sharp, onnxruntime-node, any package with a native binding -- gets
+        // `undefined` and fails with "Cannot find module ... from ''".
+        define: {
+            'import.meta.url': JSON.stringify(pathToFileURL(absPath).href),
+            'import.meta.filename': JSON.stringify(absPath),
+            'import.meta.dirname': JSON.stringify(dirname(absPath)),
+        },
     });
     const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
     const moduleObj = { exports: {} };

package/dist/function/function-meta.types.d.ts

@@ -29,10 +29,11 @@ export type FunctionRuntimeMeta = {
     featureFlag?: string;
     expose?: boolean;
     /**
-     * A sessionless function's own `auth: true`. `sessionless` carries the
-     * baseline — a `pikkuFunc` always requires a session — and this carries the
-     * tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to
-     * know whether a function is gated without running it.
+     * A sessionless function's own `auth`, as written. `sessionless` carries the
+     * baseline — a `pikkuFunc` always requires a session — and this carries what
+     * a `pikkuSessionlessFunc` declares about itself: `true` requires a session,
+     * `false` says it is public on purpose, absent says nothing. All three are
+     * needed to know whether an exposed function is gated without running it.
      */
     auth?: boolean;
     /**

package/dist/types/state.types.d.ts

@@ -6,7 +6,7 @@ import type { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types
 import type { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js';
 import type { HTTPMethod, CoreHTTPFunctionWiring, HTTPWiringsMeta } from '../wirings/http/http.types.js';
 import type { CoreMCPResource, MCPResourceMeta, MCPToolMeta, CoreMCPPrompt, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
-import type { CoreAgent, AgentsMeta } from '../wirings/agent/agent.types.js';
+import type { CoreAgent, AgentsMeta, AgentRPCFactory } from '../wirings/agent/agent.types.js';
 import type { PikkuAgentScorer, ScorerMeta } from '../wirings/agent-scorer/agent-scorer.types.js';
 import type { CoreGateway, GatewaysMeta } from '../wirings/gateway/gateway.types.js';
 import type { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
@@ -116,6 +116,11 @@ export interface PikkuPackageState {
         scorersMeta: ScorerMeta;
         /** Alias -> `provider/model`, from the `models` table in pikku.config.json. */
         modelAliases: Record<string, string>;
+        /**
+         * Set by `@pikku/core/agent` on import. Absent in a deployment unit that
+         * holds no agent, which is what keeps the agent runtime out of its bundle.
+         */
+        rpcFactory?: AgentRPCFactory;
     };
     gateway: {
         gateways: Map<string, CoreGateway>;

package/dist/wirings/agent/agent-rpc.d.ts

@@ -1,10 +1,7 @@
 import type { PikkuRawWire } from '../../types/core.types.js';
-import type { SessionService } from '../../services/user-session-service.js';
-import type { CoreUserSession } from '../../types/core.types.js';
 import type { PikkuRPC } from '../rpc/rpc-types.js';
-export type AgentRPCOptions = {
-    sessionService?: SessionService<CoreUserSession>;
-};
+import type { AgentRPCOptions } from './agent.types.js';
+export type { AgentRPCOptions };
 /**
  * `wire.rpc.agent`, implemented.
  *

package/dist/wirings/agent/agent-rpc.js

@@ -1,3 +1,4 @@
+import { pikkuState } from '../../pikku-state.js';
 import { runAgent, resumeAgentSync } from './agent-runner.js';
 import { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
 import { wrapChannelWithAGUI } from './agent-agui.js';
@@ -51,3 +52,12 @@ export const createAgentRPC = (wire, options) => {
         approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
     };
 };
+/**
+ * The RPC primitive offers `rpc.agent` but must not import this file — a static
+ * reference from `rpc-runner` pins the whole agent runtime into every
+ * deployment unit, including the ones that hold no agent. Registering the
+ * factory here inverts that: only a unit that imports `@pikku/core/agent` pays
+ * for it, which is the same seam the inspector already uses to decide whether
+ * a unit requires the agent services.
+ */
+pikkuState(null, 'agent', 'rpcFactory', createAgentRPC);

package/dist/wirings/agent/agent.types.d.ts

@@ -6,6 +6,19 @@ import type { AIProviderOptions } from '../../services/agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
 import type { ApprovalPolicy } from '../channel/channel-rpc.js';
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { PikkuRPC } from '../rpc/rpc-types.js';
+import type { SessionService } from '../../services/user-session-service.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+export type AgentRPCOptions = {
+    sessionService?: SessionService<CoreUserSession>;
+};
+/**
+ * Builds `wire.rpc.agent`. Registered by `agent-rpc.ts` when a unit imports
+ * `@pikku/core/agent`, so the RPC primitive can offer the agent surface
+ * without naming the agent runtime.
+ */
+export type AgentRPCFactory = (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC['agent'];
 export interface AgentThread {
     id: string;
     resourceId: string;

package/dist/wirings/agent/index.d.ts

@@ -1,4 +1,11 @@
+/**
+ * Registers `wire.rpc.agent`. Imported for the side effect alone so the RPC
+ * primitive can offer the agent surface without naming the agent runtime, which
+ * would pin it into every deployment unit.
+ */
+import './agent-rpc.js';
 export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './agent-helpers.js';
+export type { AgentRPCOptions, AgentRPCFactory } from './agent.types.js';
 export { wrapChannelWithAGUI } from './agent-agui.js';
 export { runAgent, resumeAgentSync } from './agent-runner.js';
 export { resolveModelAlias } from './agent-model-config.js';

package/dist/wirings/agent/index.js

@@ -1,3 +1,9 @@
+/**
+ * Registers `wire.rpc.agent`. Imported for the side effect alone so the RPC
+ * primitive can offer the agent surface without naming the agent runtime, which
+ * would pin it into every deployment unit.
+ */
+import './agent-rpc.js';
 export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './agent-helpers.js';
 export { wrapChannelWithAGUI } from './agent-agui.js';
 export { runAgent, resumeAgentSync } from './agent-runner.js';

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -52,9 +52,12 @@ export declare class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
-     * one file rather than a wing of this one; a getter rather than a field so a
-     * request that never touches an agent never builds it.
+     * Resolved through state rather than imported: naming `agent-rpc.ts` here
+     * pinned the agent runtime — runner, stream, memory, AGUI — into every
+     * deployment unit, because every unit reaches this file through
+     * `function-runner`. `@pikku/core/agent` registers the factory on import, so
+     * a unit that holds an agent has one and a unit that does not never bundles
+     * the tree behind it.
      */
     get agent(): PikkuRPC['agent'];
     remote<In = any, Out = any>(funcName: string, data: In): Promise<Out>;

package/dist/wirings/rpc/rpc-runner.js

@@ -5,7 +5,6 @@ import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 import { resolveRemoteAddonToken } from '../addon/remote-addon-auth.js';
-import { createAgentRPC } from '../agent/agent-rpc.js';
 /**
  * The session for a wire: read through `getSession` when a runner attached one,
  * otherwise whatever was placed on the wire directly.
@@ -330,11 +329,18 @@ export class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
-     * one file rather than a wing of this one; a getter rather than a field so a
-     * request that never touches an agent never builds it.
+     * Resolved through state rather than imported: naming `agent-rpc.ts` here
+     * pinned the agent runtime — runner, stream, memory, AGUI — into every
+     * deployment unit, because every unit reaches this file through
+     * `function-runner`. `@pikku/core/agent` registers the factory on import, so
+     * a unit that holds an agent has one and a unit that does not never bundles
+     * the tree behind it.
      */
     get agent() {
+        const createAgentRPC = pikkuState(null, 'agent', 'rpcFactory');
+        if (!createAgentRPC) {
+            throw new Error('Agent runtime not available: import @pikku/core/agent in this deployment unit to use rpc.agent');
+        }
         return createAgentRPC(this.wire, this.options);
     }
     async remote(funcName, data) {

package/knowledge/decisions/security/a-public-function-says-so-with-auth-false.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: A public function says so with auth: false
+description: An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
+tags: authorization, inspector, rpc
+---
+
+# A public function says so with auth: false
+
+PKU574 warns about an exposed sessionless function with no gate. Some of those
+are exactly what the author meant: a published programme, a price list, a health
+check. Before this, the only way to quiet the warning on one was a gate that
+gated nothing — an always-true permission, or `permissionsInBody: true`, which
+claims a check the body does not make. Both put a false statement into meta to
+silence a true one, and the alternative, living with the warning, teaches
+everyone to stop reading it.
+
+`auth: false` is already the field that says "no session required". Writing it
+on a `pikkuSessionlessFunc` is redundant at runtime — sessionless already means
+that — which is what makes it useful as a declaration: nobody writes it by
+accident, so its presence is the author deciding the function is public. The
+inspector now records `auth` as written (`true`, `false` or absent) instead of
+folding `false` into absent, and the check treats `false` as a gate the author
+declared, the same way it treats `permissionsInBody`.
+
+The case the warning exists for is unchanged. A sessionless function that picked
+up `expose: true` later, with nobody thinking about who may call it, has no
+`auth` at all — and still warns.
+
+**What this rules out:** a separate `public: true` flag, which would be a second
+field meaning what `auth: false` already means; reading `readonly` or the
+function's name as evidence it is safe to expose; and silencing PKU574 for every
+sessionless function, which would drop the accidental-exposure case with the
+intentional one.

package/knowledge/decisions/security/an-exposed-ungated-function-is-a-codegen-warning.md

@@ -42,7 +42,10 @@ case it would catch.
 Severity is `warn`, not `critical`. `expose: true` on an ungated sessionless
 function is legitimate for a genuinely public endpoint — a health check, a
 sign-up — so this cannot block a build without breaking correct programs. It
-fails a build only under `--fail-on-warn`.
+fails a build only under `--fail-on-warn`. And the public endpoint is not left
+warning forever: an explicit `auth: false` on a sessionless function declares it
+public on purpose and silences the check (see
+[public is declared with auth: false](./a-public-function-says-so-with-auth-false.md)).
 
 **What this rules out:** checking at boot, where the report arrives after
 deployment; checking in `pikku validate` from `.pikku` JSON, which does not

package/knowledge/decisions/security/index.md

@@ -58,6 +58,7 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [A scaffolded surface is authenticated unless the config opts out in writing](scaffold-features-are-authenticated-unless-opted-out.md) — SUPERSEDED; retains why the legacy 'auth' | 'no-auth' strings are refused rather than coerced
 - [Scenario-step functions are never externally invocable over RPC](scenario-step-functions-are-never-externally-invocable.md) — rpcExposed requires expose and rejects scenarioStep, so test steps stay reachable only from inside a scenario run
 - [Scope resolution happens at the session boundary and scope sync never deletes](scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md) — ScopeService is called when a session is built, never by the function runner, and syncScopes only ever adds — revoking is an explicit operation
+- [A public function says so with auth: false](a-public-function-says-so-with-auth-false.md) — An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
 - [Self-authentication is declared, not detected](self-authentication-is-declared-not-detected.md) — A function that authorizes callers in its own body says so with selfAuthenticated; codegen never tries to infer it
 - [Signed content URLs bind the request path and verify fail-closed](signed-content-urls-bind-the-request-path.md) — A signature that only carries timestamps authorizes every asset, and a verifier with no key must refuse rather than allow
 - [Webhook bodies are signed before they are enqueued](webhook-bodies-are-signed-before-they-are-enqueued.md) — QueueWebhookService computes the HMAC at enqueue time so the signing key never travels in the queue payload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.122",
+  "version": "0.12.123",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -24,6 +24,7 @@
   "sideEffects": [
     "./dist/errors/errors.js",
     "./dist/wirings/addon/remote-addon-auth.js",
+    "./dist/wirings/agent/agent-rpc.js",
     "./dist/wirings/rpc/rpc-runner.js",
     "./dist/wirings/workflow/pikku-scenario-service.js",
     "./dist/wirings/workflow/workflow-approval-policy.js",