@cursor/july 0.1.62 → 0.1.73

package/src/internal/turn-lease-store.ts

@@ -0,0 +1,147 @@
+/**
+ * Durable per-session turn ownership: `activeTurns` is in-memory, so servers
+ * sharing a state root would otherwise both run the same session.
+ *
+ * Exclusion, staleness and liveness refresh come from `proper-lockfile`, which
+ * the monorepo already uses for the git cache. Hand-rolling them means
+ * inferring that a process died — timeouts, heartbeats, and a takeover path
+ * that has to stay atomic while removing another owner's claim. That is where
+ * the subtle races live, and none of it is specific to turns.
+ *
+ * Liveness is lock age, not pid: containers have separate PID namespaces.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import * as lockfile from "proper-lockfile";
+
+/** A held turn lease. Releasing is idempotent. */
+export interface TurnLease {
+  release(): Promise<void>;
+}
+
+/** Reject path traversal; session ids are opaque strings from the caller. */
+function safeKey(sessionId: string): string {
+  const sanitized = sessionId
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^\.+/, "")
+    .replace(/\.+/g, "_")
+    .slice(0, 180);
+  return sanitized === "" ? "_empty" : sanitized;
+}
+
+interface HeldLock {
+  release: () => Promise<void>;
+  /** The coalesce drain nests turns, so the same session is acquired twice. */
+  refs: number;
+}
+
+export class TurnLeaseStore {
+  private readonly dir: string;
+  private readonly staleMs: number;
+  /** Locks this process holds. Their release closures cannot live on disk. */
+  private readonly held = new Map<string, HeldLock>();
+
+  constructor(dir: string, options: { ttlMs?: number } = {}) {
+    this.dir = dir;
+    // Several refreshes, so a slow owner is not mistaken for a dead one.
+    this.staleMs = options.ttlMs ?? 30_000;
+  }
+
+  private path(sessionId: string): string {
+    return join(this.dir, `${safeKey(sessionId)}.lease`);
+  }
+
+  /**
+   * Undefined when another process holds this session and is still refreshing.
+   *
+   * `onCompromised` fires when the lock is lost mid-turn — the owner stalled
+   * past the stale window and a successor took over. No lease scheme can stop
+   * that; the callback is how the displaced turn learns to stand down instead
+   * of answering alongside its successor.
+   */
+  async acquire(
+    sessionId: string,
+    onCompromised?: () => void
+  ): Promise<TurnLease | undefined> {
+    const existing = this.held.get(sessionId);
+    if (existing !== undefined) {
+      existing.refs += 1;
+      return this.handle(sessionId);
+    }
+
+    await mkdir(this.dir, { recursive: true });
+    let release: () => Promise<void>;
+    try {
+      release = await lockfile.lock(this.path(sessionId), {
+        realpath: false,
+        retries: 0,
+        stale: this.staleMs,
+        // How often the library refreshes the lock's mtime while we hold it.
+        update: 5_000,
+        onCompromised: () => {
+          this.held.delete(sessionId);
+          onCompromised?.();
+        },
+      });
+    } catch {
+      // Held elsewhere, or the store is unusable. Either way this process must
+      // not run the turn: coalescing costs latency, two servers on one session
+      // costs the conversation.
+      return undefined;
+    }
+    this.held.set(sessionId, { release, refs: 1 });
+    return this.handle(sessionId);
+  }
+
+  private handle(sessionId: string): TurnLease {
+    let released = false;
+    return {
+      release: async () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        const lock = this.held.get(sessionId);
+        if (lock === undefined) {
+          return;
+        }
+        lock.refs -= 1;
+        if (lock.refs > 0) {
+          return;
+        }
+        this.held.delete(sessionId);
+        // Throws if the lock was already compromised, which is not our problem
+        // to solve here: the successor owns it.
+        await lock.release().catch(() => {});
+      },
+    };
+  }
+
+  /** Graceful shutdown: drop every claim so a successor need not wait it out. */
+  async releaseAll(): Promise<void> {
+    for (const [sessionId, lock] of [...this.held]) {
+      this.held.delete(sessionId);
+      await lock.release().catch(() => {});
+    }
+  }
+
+  /**
+   * The session is running in another server process. Mirrors the engine's
+   * in-memory `isTurnRunning`, which only ever sees this process.
+   */
+  async runningElsewhere(sessionId: string): Promise<boolean> {
+    if (this.held.has(sessionId)) {
+      return false;
+    }
+    try {
+      return await lockfile.check(this.path(sessionId), {
+        realpath: false,
+        stale: this.staleMs,
+      });
+    } catch {
+      return false;
+    }
+  }
+}

package/src/internal/workspace.ts

@@ -7,6 +7,7 @@
  * all of this up natively through its project setting source.
  */
 
+import { execFile } from "node:child_process";
 import {
   chmod,
   copyFile,
@@ -18,7 +19,9 @@ import {
   symlink,
   writeFile,
 } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
 import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
 import { MEMORY_DIR_NAME } from "../memory.js";
 import type {
@@ -29,6 +32,8 @@ import type {
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
 import { buildIdentitySection } from "./prompt-context.js";
 
+const execFileAsync = promisify(execFile);
+
 export interface MaterializeWorkspaceOptions {
   agent: ResolvedAgent;
   workspaceDir: string;
@@ -268,6 +273,34 @@ export async function isNestedInGitRepo(dir: string): Promise<boolean> {
   return false;
 }
 
+/** Default harness parent for a nested-git agent project. */
+export function defaultLocalHarnessCwd(dirName: string): string {
+  return join(homedir(), ".cache", "agent-serve", dirName);
+}
+
+/**
+ * Give a session workspace its own git root so the harness roots *there*
+ * rather than at the enclosing repo (see {@link isNestedInGitRepo}). Without
+ * it the harness reads the outer repo's `.cursor/hooks.json`, rules, skills
+ * and `mcp.json`, and never sees the ones written into this workspace —
+ * instructions have an inline fallback, hooks have none.
+ *
+ * Best effort: a workspace that already has `.git` (a borrowed checkout or
+ * worktree) is left alone, and a failed `git init` leaves the harness where
+ * it already was.
+ */
+export async function ensureOwnGitRoot(dir: string): Promise<boolean> {
+  if (!(await isNestedInGitRepo(dir))) {
+    return false;
+  }
+  try {
+    await execFileAsync("git", ["init", "--quiet"], { cwd: dir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function materializeWorkspace(
   options: MaterializeWorkspaceOptions
 ): Promise<void> {

package/src/storage-protocol.ts

@@ -0,0 +1,247 @@
+/**
+ * Durable session KV contract: key families plus a tolerant SessionRecord
+ * decoder. This is the lockstep surface for the control plane (see
+ * `backend/server/src/agentServe/durableSessionProtocol.ts`) so a dashboard
+ * list can read Bugbot KV without importing `@cursor/july`.
+ *
+ * Additive JSON only — unknown fields are ignored. Do not put ledger
+ * (`durable-session/`) types here; those are coordination-only and must not
+ * appear in the CP session list.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * Framework-owned key root. All {@link storageKeys} values live under this
+ * prefix so a shared store can route or namespace Agent SDK data.
+ */
+export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+
+/**
+ * Exact session-record keys: `agentkit/v1/{agent}/session/{sessionId}`.
+ * Rejects `session-events/`, `durable-session/`, and the CP-owned `_cp`
+ * agent name.
+ */
+const DURABLE_SESSION_RECORD_KEY_RE =
+  /^agentkit\/v1\/([^/]+)\/session\/([^/]+)$/;
+
+/**
+ * The framework-owned key scheme. Keys are a **stable, versioned contract**
+ * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
+ * route on prefixes (e.g. event chunks to object storage, everything else
+ * to a database). Channel ids and continuation tokens are the only segments
+ * that may contain caller-controlled characters; they are URI-encoded, and
+ * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
+ * by a `sha256:…` digest — so every minted key has a bounded length that any
+ * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
+ * no matter what a caller stuffs into a token. The substitution is
+ * deterministic: writes and continuation lookups build the same key.
+ *
+ * | Key | Value |
+ * | --- | --- |
+ * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
+ *
+ * The `eval-runs` / `ab-samples` / `ab-snapshot` families are minted only
+ * by the tables `defineStorage` derives over the KV core; a backend that
+ * authors dedicated `StorageConfig.evals` / `StorageConfig.abs` groups never
+ * sees them.
+ */
+export const storageKeys = {
+  session: (agent: string, sessionId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
+  sessionPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session/`,
+  sessionEvents: (
+    agent: string,
+    sessionId: string,
+    firstIndex: number
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
+  sessionEventsPrefix: (agent: string, sessionId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
+  continuation: (
+    agent: string,
+    channelId: string,
+    continuationKey: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
+  /**
+   * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
+   * digested like other caller-controlled segments.
+   */
+  kv: (agent: string, key: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
+  kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
+  /** One playground eval-run snapshot (derived `evals` table). */
+  evalRun: (agent: string, runId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/${keySegment(runId)}`,
+  evalRunsPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/`,
+  /**
+   * One A/B metric sample (derived `abs` table); the segments mirror the
+   * dedicated table's row identity (experiment + sessionId + at).
+   */
+  abSample: (
+    agent: string,
+    experiment: string,
+    sessionId: string,
+    at: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
+  /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
+  abSnapshot: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
+} as const;
+
+/**
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
+ * Chosen so full keys stay well under common backend limits (Postgres btree
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
+ */
+export const MAX_KEY_SEGMENT_BYTES = 256;
+
+/**
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
+ * digest of the raw value when the encoding exceeds
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
+ * write path and the continuation-lookup path always agree.
+ *
+ * Exported for the session ledger, which builds its `session/` and
+ * `ledger/` keys with the same encoding rules.
+ */
+export function keySegment(raw: string): string {
+  const encoded = encodeURIComponent(raw);
+  if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
+    return encoded;
+  }
+  return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+}
+
+export function isDurableSessionRecordKey(key: string): boolean {
+  const match = DURABLE_SESSION_RECORD_KEY_RE.exec(key);
+  return match !== null && match[1] !== "_cp";
+}
+
+/** List fields of a persisted `SessionRecord`. Unknown properties are dropped. */
+export type DurableSessionRecord = {
+  sessionId: string;
+  channelId: string;
+  mode: string;
+  continuationKey: string | null | undefined;
+  title: string | undefined;
+  turnCount: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * Session metadata for history UIs. `running` is omitted unless a live
+ * overlay (the engine process) supplies it — a KV-only reader must not
+ * claim a turn is in flight.
+ */
+export type DurableSessionSummary = {
+  sessionId: string;
+  channelId: string;
+  mode: string;
+  title: string | undefined;
+  turnCount: number;
+  createdAt: string;
+  updatedAt: string;
+  running: boolean | undefined;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Tolerant `SessionRecord` decoder. Extra fields (`auth`, `purpose`, ledger
+ * extras, future keys) are ignored. Returns undefined when required list
+ * fields are missing or the wrong type.
+ */
+export function parseDurableSessionRecord(
+  value: unknown
+): DurableSessionRecord | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const sessionId = stringValue(value.sessionId);
+  const channelId = stringValue(value.channelId);
+  const mode = stringValue(value.mode);
+  const turnCount =
+    typeof value.turnCount === "number" ? value.turnCount : undefined;
+  const createdAt = stringValue(value.createdAt);
+  const updatedAt = stringValue(value.updatedAt);
+  if (
+    sessionId === undefined ||
+    sessionId.length === 0 ||
+    channelId === undefined ||
+    mode === undefined ||
+    turnCount === undefined ||
+    createdAt === undefined ||
+    updatedAt === undefined
+  ) {
+    return undefined;
+  }
+  if (
+    value.continuationKey !== undefined &&
+    value.continuationKey !== null &&
+    typeof value.continuationKey !== "string"
+  ) {
+    return undefined;
+  }
+  const continuationKey = value.continuationKey;
+  return {
+    sessionId,
+    channelId,
+    mode,
+    continuationKey,
+    title: typeof value.title === "string" ? value.title : undefined,
+    turnCount,
+    createdAt,
+    updatedAt,
+  };
+}
+
+export function summarizeDurableSessionRecord(args: {
+  record: DurableSessionRecord;
+  running?: boolean;
+}): DurableSessionSummary {
+  const { record, running } = args;
+  return {
+    sessionId: record.sessionId,
+    channelId: record.channelId,
+    mode: record.mode,
+    title: record.title,
+    turnCount: record.turnCount,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    running,
+  };
+}
+
+/**
+ * Golden persisted record: required list fields plus extras a future engine
+ * might write. Both this package and the CP decoder must accept it.
+ */
+export const GOLDEN_DURABLE_SESSION_RECORD: Record<string, unknown> = {
+  sessionId: "ses_aaaaaaaaaaaaaaaaaaaaaaaa",
+  channelId: "playground",
+  mode: "chat",
+  purpose: "live",
+  continuationKey: "cont_key_1",
+  auth: { kind: "user", userId: 42 },
+  title: "Weather in NYC",
+  turnCount: 3,
+  createdAt: "2026-08-01T12:00:00.000Z",
+  updatedAt: "2026-08-01T12:05:00.000Z",
+  extraUnknownField: { nested: true },
+};

package/src/storage.ts

@@ -52,13 +52,28 @@
  * interface is the durable mirror.
  */
 
-import { createHash } from "node:crypto";
 import type { ABMetricSample } from "./ab.js";
 import type { EvalRunSnapshot } from "./evals.js";
 import type { ABSnapshot } from "./internal/ab-snapshot.js";
 import { brandDefinition } from "./internal/brand.js";
+import { storageKeys } from "./storage-protocol.js";
 import type { JsonValue, KvCasResult, KvVersionedEntry } from "./types.js";
 
+export type {
+  DurableSessionRecord,
+  DurableSessionSummary,
+} from "./storage-protocol.js";
+export {
+  GOLDEN_DURABLE_SESSION_RECORD,
+  isDurableSessionRecordKey,
+  keySegment,
+  MAX_KEY_SEGMENT_BYTES,
+  parseDurableSessionRecord,
+  STORAGE_KEY_ROOT,
+  storageKeys,
+  summarizeDurableSessionRecord,
+} from "./storage-protocol.js";
+
 // ============================================================================
 // Sink interface
 // ============================================================================
@@ -424,115 +439,6 @@ function deriveAbsTable(config: StorageConfig): StorageABTable {
   };
 }
 
-// ============================================================================
-// Key scheme
-// ============================================================================
-
-/**
- * Framework-owned key root. All {@link storageKeys} values live under this
- * prefix so a shared store can route or namespace Agent SDK data.
- */
-export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
-
-/**
- * The framework-owned key scheme. Keys are a **stable, versioned contract**
- * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
- * route on prefixes (e.g. event chunks to object storage, everything else
- * to a database). Channel ids and continuation tokens are the only segments
- * that may contain caller-controlled characters; they are URI-encoded, and
- * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
- * by a `sha256:…` digest — so every minted key has a bounded length that any
- * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
- * no matter what a caller stuffs into a token. The substitution is
- * deterministic: writes and continuation lookups build the same key.
- *
- * | Key | Value |
- * | --- | --- |
- * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
- * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
- * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
- * | `agentkit/v1/{agent}/eval-runs/{runId}` | `EvalRunSnapshot` (derived `evals` table) |
- * | `agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` | `ABMetricSample` (derived `abs` table, append-only) |
- * | `agentkit/v1/{agent}/ab-snapshot` | `ABSnapshot` (derived `abs` table, LWW) |
- *
- * The `eval-runs` / `ab-samples` / `ab-snapshot` families are minted only
- * by the tables `defineStorage` derives over the KV core; a backend that
- * authors dedicated {@link StorageConfig.evals} / {@link StorageConfig.abs}
- * groups never sees them.
- */
-export const storageKeys = {
-  session: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
-  sessionPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session/`,
-  sessionEvents: (
-    agent: string,
-    sessionId: string,
-    firstIndex: number
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
-  sessionEventsPrefix: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
-  continuation: (
-    agent: string,
-    channelId: string,
-    continuationKey: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
-  /**
-   * Author-facing opaque JSON (see {@link HostContext.kv}). `key` is
-   * URI-encoded / digested like other caller-controlled segments.
-   */
-  kv: (agent: string, key: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
-  kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
-  /** One playground eval-run snapshot (derived `evals` table). */
-  evalRun: (agent: string, runId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/${keySegment(runId)}`,
-  evalRunsPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/`,
-  /**
-   * One A/B metric sample (derived `abs` table); the segments mirror the
-   * dedicated table's row identity (experiment + sessionId + at).
-   */
-  abSample: (
-    agent: string,
-    experiment: string,
-    sessionId: string,
-    at: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
-  /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
-  abSnapshot: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
-} as const;
-
-/**
- * Max bytes a caller-controlled key segment may occupy after URI-encoding.
- * Chosen so full keys stay well under common backend limits (Postgres btree
- * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
- * replaced by their SHA-256 digest, keeping every minted key bounded.
- */
-export const MAX_KEY_SEGMENT_BYTES = 256;
-
-/**
- * URI-encode one caller-controlled key segment, substituting a `sha256:…`
- * digest of the raw value when the encoding exceeds
- * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
- * write path and the continuation-lookup path always agree.
- *
- * Exported for the session ledger, which builds its `session/` and
- * `ledger/` keys with the same encoding rules.
- */
-export function keySegment(raw: string): string {
-  const encoded = encodeURIComponent(raw);
-  if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
-    return encoded;
-  }
-  return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
-}
-
 // ============================================================================
 // Policy resolution
 // ============================================================================

package/src/tools.ts

@@ -85,6 +85,11 @@ type ServerToolConfig<TSchema> = {
   description: string;
   execution?: "server";
   inputSchema?: TSchema;
+  /**
+   * JSON Schema for the tool's structured output (zod converted at
+   * discovery, never validated against). Advertised when declared.
+   */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   needsApproval?: ToolNeedsApproval<ToolInput<TSchema>>;
   execute: (
     input: ToolInput<TSchema>,
@@ -97,6 +102,8 @@ type AgentToolConfig<TSchema> = {
   description: string;
   execution: "agent";
   inputSchema?: TSchema;
+  /** Output JSON Schema; advertised when declared, never validated against. */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   /**
    * Shell script written into the session workspace. Receives a JSON
    * object on stdin and should print the result on stdout.