@shipfox/api-logs-dto 16.0.0 → 20.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-logs-dto",
   "license": "MIT",
-  "version": "16.0.0",
+  "version": "20.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/index.ts

@@ -48,3 +48,4 @@ export {
   sessionViewToolCallRowSchema,
   sessionViewToolResultRowSchema,
 } from './schemas/index.js';
+export {DEFAULT_STEP_LOG_TAIL_LINES, MAX_STEP_LOG_TAIL_LINES} from './tail.js';

package/src/inter-module.test.ts

@@ -1,6 +1,35 @@
 import {logsInterModuleContract} from './inter-module.js';
 
 describe('logsInterModuleContract', () => {
+  test('accepts exact-attempt tail reads and defaults the line window', () => {
+    const input = logsInterModuleContract.methods.readStepLogTail.input.parse({
+      stepId: '00000000-0000-4000-8000-000000000005',
+      attempt: 2,
+    });
+
+    expect(input).toEqual({
+      stepId: '00000000-0000-4000-8000-000000000005',
+      attempt: 2,
+      tailLines: 500,
+    });
+    expect(
+      logsInterModuleContract.methods.readStepLogTail.output.parse({
+        content: '2026-01-01T00:00:00.000Z stdout: hello',
+        totalLines: 12,
+      }),
+    ).toMatchObject({totalLines: 12});
+    expect(logsInterModuleContract.methods.readStepLogTail.output.parse(null)).toBeNull();
+  });
+
+  test('keeps the tail request bounded and exact-attempt', () => {
+    const schema = logsInterModuleContract.methods.readStepLogTail;
+    const stepId = '00000000-0000-4000-8000-000000000005';
+
+    expect(schema.input.safeParse({stepId, attempt: 1, tailLines: 0}).success).toBe(false);
+    expect(schema.input.safeParse({stepId, attempt: 1, tailLines: 2_001}).success).toBe(false);
+    expect(schema.input.safeParse({stepId, attempt: 1, tailLines: 1.5}).success).toBe(false);
+  });
+
   test('accepts server-origin append commands', () => {
     const input = logsInterModuleContract.methods.appendServerRecords.input.parse({
       jobId: '00000000-0000-4000-8000-000000000001',

package/src/inter-module.ts

@@ -1,22 +1,46 @@
 import {defineInterModuleContract, type InterModuleClient} from '@shipfox/inter-module';
 import {z} from 'zod';
 import {serverLogRecordSchema} from './schemas/index.js';
+import {DEFAULT_STEP_LOG_TAIL_LINES, MAX_STEP_LOG_TAIL_LINES} from './tail.js';
 
 const idSchema = z.string().uuid();
 
+export {DEFAULT_STEP_LOG_TAIL_LINES, MAX_STEP_LOG_TAIL_LINES} from './tail.js';
+
 /**
- * Producer-owned Logs commands used by synchronous callers. The only method
- * today is the server-origin append for server-executed steps (the tool step
- * executor): it writes already-normalized stored records through the same
- * offset-CAS and budget pipeline as the lease-bound runner route, but with
- * chunk `origin` `server` and a tail-derived CAS offset (the caller owns no
- * spool cursor). This is a trusted internal boundary, not an authorization
- * boundary: the caller must derive the identity fields from its execution
- * context rather than pass through arbitrary external input.
+ * Producer-owned Logs commands used by synchronous callers. The exact-attempt tail read and
+ * server-origin append for server-executed steps (the tool step executor) run inside this
+ * boundary. The append writes already-normalized stored records through the same offset-CAS and
+ * budget pipeline as the lease-bound runner route, but with chunk `origin` `server` and a
+ * tail-derived CAS offset (the caller owns no spool cursor). This is a trusted internal
+ * boundary, not an authorization boundary: callers must derive identity fields from their
+ * execution context rather than pass through arbitrary external input.
  */
 export const logsInterModuleContract = defineInterModuleContract({
   module: 'logs',
   methods: {
+    /** Reads one exact step attempt as bounded rendered text. */
+    readStepLogTail: {
+      input: z.object({
+        stepId: idSchema,
+        attempt: z.number().int().min(1).max(2_147_483_647),
+        tailLines: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_STEP_LOG_TAIL_LINES)
+          .default(DEFAULT_STEP_LOG_TAIL_LINES),
+      }),
+      output: z
+        .object({
+          content: z.string(),
+          totalLines: z.number().int().nonnegative().optional(),
+        })
+        .nullable(),
+      errors: {
+        'compacted-log-unavailable': z.object({}),
+      },
+    },
     appendServerRecords: {
       input: z.object({
         jobId: idSchema,

package/src/tail.ts

@@ -0,0 +1,3 @@
+/** Default and maximum line windows accepted by the bounded step-log tail operation. */
+export const DEFAULT_STEP_LOG_TAIL_LINES = 500;
+export const MAX_STEP_LOG_TAIL_LINES = 2_000;