@xenosystem/agent-interface-core 0.1.3

package/dist/workspaceKnowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceKnowledge.js","sourceRoot":"","sources":["../src/workspaceKnowledge.ts"],"names":[],"mappings":"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"}

package/dist/writeLease.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The session write lease — ADE spec §5.5, takeover with explicit semantics.
+ *
+ * > "When a human types into the agent's terminal, the agent yields, and the
+ * >  transcript records that a human intervened. **Two writers into one session
+ * >  with no arbitration corrupts the run.** Most of the terminal tier is sloppy
+ * >  here precisely because tmux gives them attach for free and they never
+ * >  modelled the handoff. This is the hard part and the part worth owning."
+ *
+ * ## What "the agent yields" can and cannot mean
+ *
+ * 🔴 The agent is a **running process**. We cannot stop it writing to its own
+ * stdout, and we should not want to: its output during a takeover is exactly
+ * the evidence a reviewer needs to see what the human interrupted. So a lease
+ * over *output* would be both unenforceable and wrong.
+ *
+ * **The lease governs INPUT — who may write INTO the session.** That is the
+ * thing we genuinely own (§2.8: we give every session a terminal and own both
+ * ends of it), and it is where the corruption actually happens: two writers
+ * interleaving keystrokes into one PTY produces a command neither of them
+ * typed. Agent output continues throughout and stays on the transcript.
+ *
+ * ## Three rules, each of which is a way to get this wrong
+ *
+ * 1. **A human PREEMPTS the agent; a human never queues behind it.** Typing is
+ *    the takeover — there is no request-and-wait, because the case this exists
+ *    for is an agent going wrong *now*.
+ * 2. **A human does NOT preempt another human.** Two humans interleaving is the
+ *    same corrupted command as a human and an agent, and "most recent typist
+ *    wins" would make it silent. The second is refused and told who holds it.
+ * 3. **The agent never takes the lease back on its own.** Return is an explicit
+ *    human act. An idle timer that silently hands control back mid-thought
+ *    would resume the agent while a human is composing — reintroducing exactly
+ *    the interleaving the lease prevents, at the least observable moment.
+ */
+/** Who may write into the session right now. */
+export type WriteLeaseHolder = {
+    kind: 'agent';
+} | {
+    kind: 'human';
+    viewerId: string;
+};
+export interface WriteLeaseState {
+    holder: WriteLeaseHolder;
+    /** When the current holder took it. */
+    since: number;
+    /** How many times a human has taken over this session, ever. */
+    interventions: number;
+}
+export type WriteLeaseTransition = {
+    ok: true;
+    state: WriteLeaseState;
+    /** True when this transition took the lease FROM the agent. */
+    agentYielded: boolean;
+} | {
+    ok: false;
+    code: 'held_by_another_human';
+    heldBy: string;
+    reason: string;
+} | {
+    ok: false;
+    code: 'not_holder';
+    reason: string;
+};
+/** A fresh session: the agent writes, nobody has intervened. */
+export declare function openWriteLease(now: number): WriteLeaseState;
+/**
+ * A human types. This IS the takeover — §5.5 has no separate request step.
+ *
+ * Re-taking a lease you already hold is a no-op rather than an error: a human
+ * types many keystrokes, and every one of them after the first must not count
+ * as a new intervention or the transcript would report a hundred takeovers.
+ */
+export declare function humanTakesWriteLease(state: WriteLeaseState, viewerId: string, now: number): WriteLeaseTransition;
+/**
+ * The human hands the session back. Rule 3: only this returns the lease.
+ *
+ * Someone who does not hold it cannot release it — otherwise one surface could
+ * hand the agent control while another human was mid-command.
+ */
+export declare function humanReleasesWriteLease(state: WriteLeaseState, viewerId: string, now: number): WriteLeaseTransition;
+/**
+ * Whether the host may inject agent-side input right now.
+ *
+ * ⚠️ INPUT only. Agent OUTPUT is never gated — see the header. A caller that
+ * used this to suppress output would hide the very thing a reviewer needs to
+ * understand what the human interrupted.
+ */
+export declare function agentMayWrite(state: WriteLeaseState): boolean;
+/** Who holds it, for a surface to show without inspecting the union. */
+export declare function describeWriteLease(state: WriteLeaseState): string;
+//# sourceMappingURL=writeLease.d.ts.map

package/dist/writeLease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeLease.d.ts","sourceRoot":"","sources":["../src/writeLease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gBAAgB,CAAA;IACxB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IACE,EAAE,EAAE,IAAI,CAAA;IACR,KAAK,EAAE,eAAe,CAAA;IACtB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAA;CACtB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAErD,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,oBAAoB,CAyBtB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,oBAAoB,CAatB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAE7D;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAIjE"}

package/dist/writeLease.js

@@ -0,0 +1,108 @@
+/**
+ * The session write lease — ADE spec §5.5, takeover with explicit semantics.
+ *
+ * > "When a human types into the agent's terminal, the agent yields, and the
+ * >  transcript records that a human intervened. **Two writers into one session
+ * >  with no arbitration corrupts the run.** Most of the terminal tier is sloppy
+ * >  here precisely because tmux gives them attach for free and they never
+ * >  modelled the handoff. This is the hard part and the part worth owning."
+ *
+ * ## What "the agent yields" can and cannot mean
+ *
+ * 🔴 The agent is a **running process**. We cannot stop it writing to its own
+ * stdout, and we should not want to: its output during a takeover is exactly
+ * the evidence a reviewer needs to see what the human interrupted. So a lease
+ * over *output* would be both unenforceable and wrong.
+ *
+ * **The lease governs INPUT — who may write INTO the session.** That is the
+ * thing we genuinely own (§2.8: we give every session a terminal and own both
+ * ends of it), and it is where the corruption actually happens: two writers
+ * interleaving keystrokes into one PTY produces a command neither of them
+ * typed. Agent output continues throughout and stays on the transcript.
+ *
+ * ## Three rules, each of which is a way to get this wrong
+ *
+ * 1. **A human PREEMPTS the agent; a human never queues behind it.** Typing is
+ *    the takeover — there is no request-and-wait, because the case this exists
+ *    for is an agent going wrong *now*.
+ * 2. **A human does NOT preempt another human.** Two humans interleaving is the
+ *    same corrupted command as a human and an agent, and "most recent typist
+ *    wins" would make it silent. The second is refused and told who holds it.
+ * 3. **The agent never takes the lease back on its own.** Return is an explicit
+ *    human act. An idle timer that silently hands control back mid-thought
+ *    would resume the agent while a human is composing — reintroducing exactly
+ *    the interleaving the lease prevents, at the least observable moment.
+ */
+/** A fresh session: the agent writes, nobody has intervened. */
+export function openWriteLease(now) {
+    return { holder: { kind: 'agent' }, since: now, interventions: 0 };
+}
+/**
+ * A human types. This IS the takeover — §5.5 has no separate request step.
+ *
+ * Re-taking a lease you already hold is a no-op rather than an error: a human
+ * types many keystrokes, and every one of them after the first must not count
+ * as a new intervention or the transcript would report a hundred takeovers.
+ */
+export function humanTakesWriteLease(state, viewerId, now) {
+    if (state.holder.kind === 'human') {
+        if (state.holder.viewerId === viewerId) {
+            return { ok: true, state, agentYielded: false };
+        }
+        // Rule 2. Refusing NAMES the holder, so the second human can talk to them —
+        // the same shape as a refused claim in the coordination spec, and for the
+        // same reason: a bare failure leaves the caller to spin or guess.
+        return {
+            ok: false,
+            code: 'held_by_another_human',
+            heldBy: state.holder.viewerId,
+            reason: `${state.holder.viewerId} is typing into this session; two writers interleave into one command`,
+        };
+    }
+    return {
+        ok: true,
+        state: {
+            holder: { kind: 'human', viewerId },
+            since: now,
+            interventions: state.interventions + 1,
+        },
+        agentYielded: true,
+    };
+}
+/**
+ * The human hands the session back. Rule 3: only this returns the lease.
+ *
+ * Someone who does not hold it cannot release it — otherwise one surface could
+ * hand the agent control while another human was mid-command.
+ */
+export function humanReleasesWriteLease(state, viewerId, now) {
+    if (state.holder.kind !== 'human' || state.holder.viewerId !== viewerId) {
+        return {
+            ok: false,
+            code: 'not_holder',
+            reason: 'only the holder can return the session to the agent',
+        };
+    }
+    return {
+        ok: true,
+        state: { holder: { kind: 'agent' }, since: now, interventions: state.interventions },
+        agentYielded: false,
+    };
+}
+/**
+ * Whether the host may inject agent-side input right now.
+ *
+ * ⚠️ INPUT only. Agent OUTPUT is never gated — see the header. A caller that
+ * used this to suppress output would hide the very thing a reviewer needs to
+ * understand what the human interrupted.
+ */
+export function agentMayWrite(state) {
+    return state.holder.kind === 'agent';
+}
+/** Who holds it, for a surface to show without inspecting the union. */
+export function describeWriteLease(state) {
+    return state.holder.kind === 'agent'
+        ? 'the agent is driving'
+        : `${state.holder.viewerId} has taken over`;
+}
+//# sourceMappingURL=writeLease.js.map

package/dist/writeLease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeLease.js","sourceRoot":"","sources":["../src/writeLease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAyBH,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,EAAE,CAAA;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAsB,EACtB,QAAgB,EAChB,GAAW;IAEX,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACvC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAA;QACjD,CAAC;QACD,4EAA4E;QAC5E,0EAA0E;QAC1E,kEAAkE;QAClE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,uBAAuB;YAC7B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ;YAC7B,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,uEAAuE;SACxG,CAAA;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE;YACL,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE;YACnC,KAAK,EAAE,GAAG;YACV,aAAa,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC;SACvC;QACD,YAAY,EAAE,IAAI;KACnB,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAsB,EACtB,QAAgB,EAChB,GAAW;IAEX,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACxE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,qDAAqD;SAC9D,CAAA;IACH,CAAC;IACD,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE;QACpF,YAAY,EAAE,KAAK;KACpB,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAsB;IAClD,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,CAAA;AACtC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,kBAAkB,CAAC,KAAsB;IACvD,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO;QAClC,CAAC,CAAC,sBAAsB;QACxB,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,iBAAiB,CAAA;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@xenosystem/agent-interface-core",
+  "version": "0.1.3",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XENO-CORPORATION/xeno-agent-interface.git",
+    "directory": "packages/core"
+  },
+  "dependencies": {
+    "@xenosystem/agent-interface-contract": "0.1.3"
+  },
+  "scripts": {}
+}